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Preface 



The RT-11 Programmer's Reference Manual describes the programmed re- 
quests and subroutines that are available in the system macro library 
(SYSMAC.SML) and system subroutine library (SYSLIB.OBJ). It provides 
programming examples that show how to use programmed requests and 
subroutines. 

Chapter 1, Introduction to Advanced RT-11 Programming, describes the 
implementation and use of the programmed requests and the FORTRAN- 
callable subroutines. 

Chapter 2, Programmed Request Description and Examples, describes the 
individual programmed requests in detail. Program examples are included 
for each request. In addition, macros and subroutines that are used in im- 
plementing device handlers and interrupt service routines are described. 

Chapter 3, System Subroutine Description and Examples, describes in de- 
tail all the RT-11 FORTRAN-callable subroutines. This chapter also con- 
tains examples of the use of the calls to the system subroutine library. 

Appendix A, Display File Handler, describes the graphics support for the 
RT-11 operating system. Program examples are included to help you de- 
velop your own display program. 

Appendix B, System Macro Library, is a listing of the RT-11 System Macro 
Library (SYSMAC.SML). 

This manual is written for an advanced -level user. If you have no RT-11 
experience, or very little, read: 

Introduction to RT-11 

RT-11 System User's Guide 

RT-11 System Utilities Manual 

PDP-11 MACRO-11 Language Reference Manual 

In addition, FORTRAN programmers should read: 

RT-11/RSTS/E FORTRAN IV User's Guide 
PDP-11 /FORTRAN Language Reference Manual 

If you are interested in additional programming techniques or other system 
programming topics, read the RT-11 Software Support Manual. 
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Chapter 1 

Introduction to Advanced RT-11 Programming 

Programmed requests and system subroutines are available as part of the 
RT— 11 Operating System and can aid you in writing reliable and efficient 
programs. 

Programmed requests provide a number of services to application pro- 
grams. The requests function as calls to routines in the RT-11 monitor that 
perform these services. As system macros, they are defined in a system 
macro library that is stored on the system volume and named SYS- 
MAC.SML. In addition, macro routines are available in the system macro 
library that can help you write device handlers and interrupt service 
routines. 

If you are a FORTRAN programmer, you can access the RT-11 monitor 
services through calls to the system subroutine library called SYSLIB.OBJ, 
which is stored on the system volume. A character string manipulation 
package and two-word integer support routines are included in this library. 
The SYSLIB subroutines allow you to write almost all application pro- 
grams in FORTRAN without having to do any assembly language coding. 

This chapter tells you how to use programmed requests and subroutines 
effectively in your programs. Examples are provided to demonstrate their 
flexibility and value in working programs. 

1.1 Programmed Requests 

You issue a programmed request in your source program when a certain 
monitor service is required. The programmed request expands into the ap- 
propriate machine language code during assembly time. During program 
execution, this code requests the resident monitor to supply the service 
represented by the programmed request. 

The services involve the following processes: 

1. Initialization and control of operating system characteristics 

2. Allocating system resources and reporting status 

3. Command interpretation 

4. File operations 

5. Input/output operations 

6. Foreground/background communications 

7. Timer support 

8. Program termination or suspension 

9. System job communications 

10. Extended memory functions 
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The system macro library (SYSMAC.SML) also contains several macros 
that are not programmed requests. These macros are provided to aid you in 
writing: 

1. Interrupt service routines 

2. Device handlers 

3. Memory management control blocks 

They are described in Chapter 2 along with the programmed requests. 

Components of the RT-11 Operating System that support programmed re- 
quests are as follows: 

1. Single- Job Monitor 

The single-job (SJ) monitor supports most of the programmed requests. 
Table l-i lists the programmed requests that are supported by the SJ 
monitor. These programmed requests can manipulate files, perform in- 
put and output, set timer routines, check system resources and status, 
and terminate program operations. 

2. Foreground/Background Monitor 

Some programmed requests are provided for the foreground/back- 
ground (FB) monitor only. Table 1-5 lists the programmed requests 
that are supported by the FB monitor in addition to those listed in 
Table 1-4. These programmed requests allow a program to set timer 
routines, suspend and resume jobs, and send messages and data be- 
tween foreground and background jobs. 

3. Extended Memory Monitor 

The extended memory (XM) monitor provides additional programmed 
requests and features above those found in the FB monitor. The XM 
monitor extends the memory support capability of RT-11 beyond the 
28K-word (plus I/O page) restriction imposed by the 16-bit address size. 
The XM monitor's programmed requests extend a program's effective 
logical addressing space (see Table 1-5). 

4. Multiterminal Feature 

The multiterminal feature of RT-11 allows your program to perform 
character input/output on up to 16 terminals. Programmed requests are 
available to perform input/output, attach and detach a terminal for 
your program, set terminal and line characteristics, and return system 
status information. 

5. System Job Support 

System job support allows users in a foreground/background or ex- 
tended memory environment to extend the present standard 
foreground/background system to include up to eight jobs. Two system 
jobs are presently provided with the RT-11 system: the error logger and 
the device queue program. Programmed requests allow programs to 
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copy channels from other jobs, obtain job status information about jobs 
in the system, and send messages and data between any jobs in the 
system. The RT-11 Software Support Manual describes the system job 
feature in more detail. 

Programmed requests perform most system resource control and interroga- 
tion functions. However, some communication is accomplished by directly 
accessing two memory areas: the system communication area and the mon- 
itor fixed-offset area. 

The system communication area resides in locations 40 to 57(octal) and 
contains parameters that describe and control execution of the current job. 
This area holds information such as the Job Status Word, starting address 
of the job. User Service Routine (USR) swapping address, and the address of 
the start of the resident monitor. Some of this information is supplied by 
your program, while other data is supplied by the monitor and may not be 
changed. 

The second memory communication area, the fixed-offset area, is accessed 
by a fixed-address offset from the start of the resident monitor. This area 
contains system values used to control monitor operation. Your program 
can examine or modify these values to determine the condition of the opera- 
ting environment while a job is running. The RT-11 Software Support 
Manual describes in detail both the system communication area and the 
fixed-offset area. 

This manual specifically describes programmed requests for RT-11 Version 
5. Programmed requests for earlier versions of RT-11 and guidelines for 
their conversion are treated in Sections 1.1.4 and 1.1.5. 

1.1.1 Programmed Request Implementation 

1.1.1.1 EMT Instructions — A programmed request is a macro call followed 
by the necessary number of arguments. The macro code that corresponds to 
the macro call of a programmed request is expanded by the MACRO assem- 
bler when the programmed request appears in your program. The expan- 
sion arranges the arguments of the programmed request for the monitor 
and generates an EMT (emulator trap) instruction. 

When an EMT instruction is executed, control passes to the monitor. The 
low-order byte of the EMT code provides the monitor with the information 
that tells it what monitor service is being requested. 

The execution of the EMT generates a trap through vector location 30. This 
vector location is loaded at boot time with an address pointing to a location 
in the monitor. The monitor location contains the EMT processing code that 
services the interrupt caused by the EMT instruction. 

Table 1—1 shows the codes that may appear in the low-order byte of an EMT 
instruction and the interpretation of these codes by the monitor. 
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Table 1-1: EMT Codes 



Low-Order Byte Interpretation 



377 Reserved; RT-11 ignores this EMT and returns control to the 

user program immediately. 

376 Used internally by the RT-11 monitor; your programs should 

not use this EMT since its use would lead to unpredictable re- 
sults. 

375 Programmed request with several arguments; RO points to a 

block of arguments that supports the user request. 

374 Programmed request with one argument; RO contains a function 

code in the high-order byte and a channel code in the low-order 
byte. 

360-373 Used internally by the RT-11 monitor; your programs should 

never use these EMT codes since their use would lead to unpre- 
dictable results. 

340-357 Programmed requests with the arguments on the stack and/or 

inRO. 

0-337 Version 1 programmed requests with arguments both on the 

stack and in RO. They are supported for binary compatibility 
with Version 1 programs. 



EMT instructions should never appear in your programs except through 
programmed requests. 

1.1.1.2 System Control Path Flow — Figure 1-1 shows system flow when a 
programmed request is executed. 

In Figure 1-1, a programmed request in an application (or system utility) 
program is implemented with an EMT instruction. When your program is 
executed, the EMT instruction transfers control to the EMT processor code 
in the monitor. The user program counter (PC) and processor status word 
(PSW) are pushed onto the stack, and the contents of location 30 are placed 
in the program counter. Location 30 points to the EMT processor code in 
the monitor. Location 32 contains the PSW for the EMT trap. Byte 52 of the 
system communication area is loaded with an error code by the monitor if 
the monitor detects any errors during the EMT processing. In addition, the 
EMT processor uses RO to pass back information to the program. All other 
registers except SP are preserved; .CSIGEN and .CSISPC return informa- 
tion on the stack. 

The monitor either processes a programmed request entirely when it is 
issued or it performs partial processing and queues the request for further 
processing. The requests that require queued processing support completion 
routines (see Section 1.1.3.5). If a request results in an error prior to being 
queued, the completion routine is not entered, and the monitor returns to 
the user program with the carry bit set. If the request is queued, the com- 
pletion routine is entered upon completion of further processing, regardless 
of the outcome. 
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Figure 1-1: System Flow During Programmed Request Execution 
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1.1.2 System Conventions 

This section describes the system conventions that must be followed for the 
correct operation of programmed requests. 

1.1.2.1 Programmed Request Format — To issue programmed requests from 
assembly language programs, you must set up the arguments in correct 
order and issue the appropriate EMT instruction. Macros have been created 
to help you do this. They are contained in the system macro library named 
SYSMAC.SML. Their use is recommended for maintaining program com- 
patibility with future releases of RT-11 and for program readability. The 
macro names for all programmed requests start with a period (.) to distin- 
guish them from symbols and macros you define. 

Arguments supplied to a programmed request must be valid assembler 
expressions since the arguments are used as source fields in the instruc- 
tions (such as a MOV instruction) when the macros are expanded at assem- 
bly time. All programmed requests that appear in your program must ap- 
pear in a .MCALL directive to make the macro definition available from 
the system macro library, SYSMAC.SML. If the programmed request is 
specified by a .MCALL directive, the programmed request is obtained from 
the system macro library at assembly time. Alternatively, you can enable 
the automatic .MCALL feature of MACRO by using the .ENABL MCL 
directive. 

Programmed requests have two formats that are accepted by the monitor. 
The first format specifies the programmed request followed by the argu- 
ments required by the request. The second format specifies the pro- 
grammed request, the address of the argument block, and the arguments 
that will be contained in the argument block. Because the way you can set 
up the argument block and specify arguments to a programmed request can 
vary, read the sections on programmed request format and on blank argu- 
ments to be sure of correct programmed request operation. 

FORMAT 1 

The first format for programmed requests is as follows: 

.PRGREQ Argl,Arg2,...,Argn 
where: 

.PRGREQ is the name of the programmed request 

Argl,Arg2,...,Argn are the arguments used with the request 

Programmed requests using this format generate either an EMT 374 in- 
struction or EMT 340 through 357 instructions. 

Programmed requests that use an EMT 374 instruction set up RO with the 
channel number in the even (low-order) byte and the function code in the 
odd (high-order) byte, as shown in Figure 1-2. 
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Figure 1-2: EMT 374 Argument 

15 



87 



RO 
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One programmed request that generates an EMT 374 is .DATE. The macro 
for this programmed request appears in the system macro library as: 

.MACRO .DATE 

MOV #10.*'0^00 tZO 

EMT •'0374 
.ENDM 

The function code, which in this case is lO(decimal) is placed in the high- 
order byte of RO. A channel code of is placed in the low-order byte. 

For EMT 340 through 357, if there are arguments, they are placed either 
on the stack, in RO, or in RO and on the stack. 

The programmed request .CSIGEN is an example of a programmed request 
that generates an EMT 344. A simplified macro expansion of this pro- 
grammed request is: 

.MACRO .CSIGEN DEVSPC tOEFEXT tCSTRNG tLI NBUF 



LINBUF »-(B. ) 
(G. ) 



. IIF NB <LINBUF> MOU 

MOV DEVSPCj-(6.) 
,IIF NB <LINBUF> INC 

MOM DEFEKTt-(B.) 
.IF B CSTRNG 

CLR -(6.) 
, IFF 
.IF IDN CSTRNG t»0 

CLR -(G.) 
. IFF 

MOM CSTRNG, -(G.) 
.ENDC 
.ENDC 

EMT ■-03Ua 
.ENDM 

When this programmed request is executed, all the specified arguments are 
placed on the user stack. Thus, the user stack would appear as shown in 
Figure 1-3. 

Figure 1-3: Stack Set by .CSIGEN Programmed Request 

High Addresses 



Stack Pointer => 
Low Addresses 



LINBUF 



DEVSPC 



DEFEXT 



CSTRING 



Introduction to Advanced RT-11 Programming 1-7 



The EMT processor then uses these arguments in performing the function 
of the programmed request .CSIGEN. 

FORMAT 2 

The second format for programmed requests is as follows: 



.PRGREQ Area,Argl,Arg2,...,Argn 



where: 



.PRGREQ 

Area 
Argl,Arg2,...,Argn 



is the name of the programmed request 

is the address of an argument block 

are the arguments that will be contained in the 

argument block 



This format generates an EMT 375 instruction. Programmed requests that 
call the monitor via an EMT 375 use RO as a pointer to an argument block. 
In general, the argument block appears as shown in Figure 1-4. 

Figure 1-4: EMT 375 Argument Block 
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Argument n 



The programmed request format uses Area as a pointer to the argument 
block that contains the arguments Argl through Argn. 

.PRGREQ Area,Argl,...,Argn 

Blank fields are permitted. However, if the Area argument is empty, the 
macro assumes that RO points to a valid argument block. If any of the fields 
Argl to Argn are empty, the corresponding entries in the argument list are 
left untouched. Thus, 

.PRGREQ Area, Argl, Arg2 

points RO to the argument block at Area and fills in the first and second 
arguments, while 

.PRGREQ Area 
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points RO to the block and fills in the first word — that is, the function 
code and channel number — without filling in any other arguments. Ar- 
guments that are left blank are discussed in the following section. 

1 .1 .2.2 Blank Arguments — Any programmed request that uses an argument 
block assumes that any argument left blank has been previously loaded by 
your program into the appropriate memory location (exceptions to this are 
the .CHCOPY and .GTJB requests). For example, when the programmed 
request 

.PRGREQ Area, Argl, Arg2 

is assembled, RO will point to the first word of the argument block. The first 
word has the function code in the high-order byte and the channel number 
in the low-order byte. Argl is in the second word of the argument block 
(that is, in address RO plus 2), while Arg2 is in RO plus 4. 

There are two ways to account for arguments. You can let the MACRO 
assembler generate the instructions needed to fill up the argument block at 
run time, or you can write these instructions in your program, leaving the 
arguments in the programmed request blank for those that you have writ- 
ten in. DIGITAL recommends that you let MACRO generate the instruc- 
tions, both for program clarity and for reduced chance of programming 
error. 

The following examples are all equivalent in that the arguments have been 
accounted for either in the program instructions or in the programmed 
request. 

MOV «ARG1 (AREA + Z 
MOV «ARGZ>AREA+4 

.PRGREQ »AREA 

is equivalent to 

MOV «AREA*RO 

.PRGREO »#ARG1»«ARGZ 

and also to 

MOV «AREA*RO 

MOV «ARG1 »Z(RO) 

MOV «ARG2*4(R0) 

MOV #CODE#^00!CHANNEL .(RO) 

.PRGREO 

This last example sets up all the arguments for the programmed request 
prior to executing the programmed request. 

The following example shows how arguments are specified to the .TWAIT 
programmed request. 
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.TITLE 


EXWAIT.MAC 




•MCALL 


.PRINT t. TWAIT 


START: 






WAIT: 


.TWAIT 


wEMTLST 




.PRINT 


«MSG 




BR 


WAIT 


EMTLST: 


.BYTE 


,2a 




.WORD 


TIME 


TIME; 


.WORD 


»10.*G0 


MSG: 


.ASCIZ 


/PRINT THIS EMERY TEN SECONDS/ 




.END 


START 



The .TWAIT programmed request suspends a program and requires two 
arguments. The first argument is area, which points to the address of a 
two-word EMT argument block; the second argument is Time, which is a 
pointer to two words of time (high-order first, low-order second) expressed 
in ticks. In the example shown above, EMTLST is specified as an argument 
with the programmed request that points to the address of the EMT argu- 
ment block. The first word of the argument block has a zero stored in the 
low-order byte representing the channel number and a function code of 24 
stored in the high-order byte. The second word contains a symbolic pointer 
to the location (the second argument), which specifies the amount of time 
that the program will be suspended. It is defined as two words and, in this 
example, represents a 10-second interval. When run, the example program 
prints its message every ten seconds. 

1.1.2.3 Addressing Modes — You must make certain that the arguments 
specified are valid source fields and that the address accurately represents 
the value desired. If the value is a constant or symbolic constant, use the 
immediate addressing mode [#]. If the value is in a register, use the regis- 
ter symbol [Rn]. If the value is in memory, use the label of the location 
whose value is the argument. 

A common error is to use n rather than #n for numeric arguments. For 
example, when a direct numerical argument is required, the immediate 
mode causes the correct value to be put into the argument block. Thus 

.PRGREQ #Area,#4 

is correct, while 

.PRGREQ #Area,4 

is not correct since the contents of location 4 are placed into the argument 
block instead of the desired value 4. 

However, the form 

.PRGREO LISTfNUMBER 



LIST: .WORD AREA 
NUMBER: .WORD a 

is correct since the contents of LIST are the argument block pointer and the 
contents of NUMBER are the data value. 
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NOTE 

All registers except RO are preserved across a programmed 
request. In certain cases, RO contains information passed 
back by the monitor; however, unless the description of a 
request indicates that a specific value is returned in RO, the 
contents of RO are unpredictable upon return from the re- 
quest. Also, with the exception of calls to the Command 
String Interpreter, the position of the stack pointer is pre- 
served across a programmed request. 

You must be sure that the selected mode generates the correct value as a 
source operand in a MOV instruction. Check the programmed request 
macro in the Macro Library (SYSMAC.SML) and expand the programmed 
request by hand or with the macro assembler (by using the .LIST MEB 
directive) to be sure of correct results. 

1.1.2.4 Keyword Macro Arguments — The RT-11 MACRO assembler sup- 
ports keyword macro arguments. All the arguments used in programmed 
request calls can be encoded in their keyword form (see the PDP-11 
MACRO— 11 Language Reference Manual for details). 

In EMT 375 programmed requests, the high byte of the first word of the 
area (pointed to by RO) contains an identifying code for the request. Nor- 
mally, this byte is set if the macro invocation of the programmed request 
specifies the area argument, and it remains unaffected if the programmed 
request omits the area argument. If the macro invocation contains 
CODE = SET, the high byte of the first word of the area is always set to the 
appropriate code, whether or not area is specified. 

If CODE = NOSET is in the macro invocation, the high byte of the first 
word of area remains unaffected. This is true whether or not area is speci- 
fied. This allows you to avoid setting the code when the programmed re- 
quest is being set up. This might be done because it is known to be set 
correctly from an earlier invocation of the request using the same area, or 
because the code was statically set during the assembly process. 

1.1.2.5 Channels and Channel Numbers — A channel is a data structure that 
is a logical connection between your program and a file on a mass storage 
device or on a serial device such as the line printer or terminal. The system 
provides 16(decimal) channels by default. When a file is opened on a partic- 
ular device, a channel number is assigned to that file. The channel number 
can have an octal value from to 376 (0 to 254 decimal). Thus, your pro- 
gram first opens a channel through a programmed request by specifying 
the device and/or file name, file type, and a channel number to the monitor. 
Your program refers to that file or device in all I/O operations thereafter by 
the assigned channel number. You can specify a device (non-file-structured) 
or a device and file name (file-structured). 

Channel 255(decimal) is reserved for system use. Channel 15(decimal) is 
used by the system's overlay handler. 
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1.1.2.6 Device Blocks — A device block is a four-word block of Radix-50 
information. You set up the block to specify a physical or logical device 
name, file name, and file type for use with a programmed request. This 
information is passed to the monitor when your program opens a file. The 
monitor uses the information to locate the referenced device and the file 
name in the corresponding directory. 

For example, a device block representing the file FILE.TYP on device DK: 
could be written as 

.RAD50 /DK / 
.RAD50 /FIL/ 
.RAD50 /E / 
.RAD50 /TYP/ 

The first word contains the device name, the second and third words con- 
tain the file name, and the fourth word contains the file type. Device, file 
name, and file type must each be left-justified in the appropriate field. This 
string could also have been written as 

.RAD50 /DK FILE TYP/ 

Spaces must fill out each field. Also, the colon and period separators must 
not appear in the string since they are only used by the Command String 
Interpreter to delimit the various fields. 

If the first word of a device block is the name of a mass-storage device such 
as a disk and the second word of the block is 0, the device block refers to an 
entire volume of the mass storage device in a non-file-structured manner. 

1 .1 .2.7 Programmed Request Errors — Programmed requests use three meth- 
ods of reporting errors detected by the monitor: 

1. Setting the carry bit of the processor status word (PSW) 

2. Reporting the error code in byte 52 of the system communications area 

3. Generating a monitor error message 

If a programmed request has been executed unsuccessfully, the monitor 
returns to your program with the carry bit set. The carry bit is returned 
clear after the normal termination of a programmed request. Almost all 
requests should be followed by a Branch Carry Set (BCS) or Branch Carry 
Clear (BCC) instruction to detect a possible error. 

Because some programmed requests have several error codes — that is, 
errors can be generated for different reasons — byte 52 in the system com- 
munications area is used to receive the error code. Thus, when the carry bit 
is set, check byte 52 to find out the kind of error that occurred in the 
programmed request. The meanings of values in the error byte are de- 
scribed individually for each request. The error byte is always zero when 
the carry bit is clear. Your program should reference byte 52 with absolute 
addressing. Always address location 52 as a byte, never as a word, since 
byte 53 has a different usage. The following example shows how byte 52 
can be tested for the error code. 
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ERRBYT=52 

.PRGREQ AREA tARGl ». . . .ARG2 

BCS ERROR 



ERROR: TSTB §«ERRBYT 



Error messages generated by the monitor are caused by fatal errors, which 
cause your program to terminate immediately. Some fatal errors can be 
intercepted and have their values returned in byte 52 (see the 
.HERR/.SERR programmed requests). 

1.1.2.8 User Service Routine (USR) Requirement — Many programmed re- 
quests require the USR to be in memory. Some of these requests always 
require a fresh copy of the USR to be read in because the code to execute 
them resides in the USR buffer area. Since the buffer area gets overlaid by 
data used to perform other system functions, the USR must be read in from 
the system device even if there is a copy of the USR presently in memory. 
Table 1-2 shows the programmed requests that require the USR. 

Table 1-2: Programmed Requests Requiring the USR 





luest 




Monitor 




Re( 


SJ 


FB 


XM 


.CDFN 




yes* 


no 


no 


.CLOSE (see Note 1) 


yes 


yes 


yes 


.CSIGEN 




yes 


yes 


yes 


.CSISPC 




yes 


yes 


yes 


.DET,KTE 




yes 


yes 


yes 


.DSTATUS 




yes 


yes 


yes 


.ENTER 




yes 


yes 


yes 


.EXIT 




yes 


yes 


yes 


.FETCH 




yes 


yes 


yes 


.FPROT 




yes 


yes 


yes 


.GTLIN 




yes 


yes 


yes 


.HRESET 




yes 


no 


no 


.LOCK (see 


Note 2) 


yes 


yes 


yes 


.LOOKUP 




yes 


yes 


yes 


.QSET 




yes* 


yes* 


yes 


.RELEAS 




yes 


yes 


yes 


.RENAME 




yes 


yes 


yes 


.SFDAT 




yes 


yes 


yes 


.SRESET 




yes* 


no 


no 


.TLOCK (see Note 3) 


yes 


yes 


yes 



Note 1: Only if channel was opened with an .ENTER pro- 
grammed request 

Note 2: Only if the USR is in a swapping state 

Note 3: Only if the USR is not in use by another job 

* The requests marked with an asterisk always require a 
fresh copy of the USR to be read in before they can be 
executed. 
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USR requirements for programmed requests differ between the SJ and FB 
monitors as shown in the table. The .CLOSE programmed request on non- 
file-structured devices, such as a line printer or terminal, does not require 
the USR under any monitor. 

The USR is not reentrant and cannot be shared by concurrent jobs. Thus, 
when the USR is in use by one job, another job requiring it must queue up 
for it. This is particularly important for concurrent jobs when devices such 
as magnetic tape or cassette are active. For example, USR file operations 
on tape devices require a sequential search of the tape. When a background 
program is running the USR, the foreground job is locked out until the tape 
operation is completed. You should be aware that this operation may take 
considerable time. The .SPFUN request can be used to perform asynchro- 
nous directory operations on tape. In the FB and XM monitors, the .TLOCK 
request can be used by a job to check USR availability. 

Any request that requires the USR to be in memory can also require that a 
portion of your program be saved temporarily in the system device swap file 
(that is, "swapped out" and stored in the file SWAP.SYS to provide room for 
the USR). The USR is then read into memory. Although swapping is invisi- 
ble to you in normal operation, you must be aware of it and take some care 
in your programming. For example, the argument block being passed to the 
USR must not be in the area that is swapped over. You can optimize pro- 
grams so that they require little or no swapping, thereby saving time. 

Consider the following items if a swap operation is necessary. 

1. The background job 

If a .SETTOP request in a background job specifies an address beyond 
the point at which the USR normally resides, a swap is required when 
the USR is called. Section 2.79 details the operation of the .SETTOP 
request. This case is not encountered in XM because the USR is always 
resident. 

2. The value of location 46 

If you assemble an address into word 46 or move a value there while the 
program is running, RT-11 uses the contents of that word as an alter- 
nate place to swap the USR. If location 46 is zero, this indicates that the 
USR will be at its normal location in high memory. If the USR does not 
require swapping, this value is ignored. 

A foreground job must always have a value in location 46 unless it is 
certain that the USR will never be swapped. If the foreground job does 
not allow space for the USR and a swap is required, a fatal error occurs. 
The SET USR NOSWAP command makes the USR permanently resi- 
dent. 

If you specify an alternate address in location 46, the SJ monitor does 
not verify the validity of the USR swap address. Thus, if the area to be 
swapped overlays the resident monitor, the system is destroyed. 

3. Monitor offset 374 

The contents of monitor offset 374 indicate the size of the USR in bytes. 
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Programs should use this information to dynamically determine the 
size of the region needed to swap the USR. 

4. Protecting program areas 

Make sure that certain areas of your program do not get overlaid when 
you swap in the USR. These areas are the program stack, any parame- 
ter block for calls to the USR, the EMT instruction that invoked the 
USR, I/O buffers, device handlers, interrupt service routines, queue 
elements, defined channels, and completion routines in use when the 
USR is being called. 

The RT—11 Software Support Manual provides additional information on 
the USR. 

1.1.3 Using Programmed Requests 

This section describes how to use and implement programmed requests to 
access the various monitor services. Chapter 2 contains, in alphabetical 
order, detailed descriptions of each request, including examples. 

1.1.3.1 Initialization and Control — Typically, you use several programmed 
requests to control the operating environment in which your program is 
running. These requests can include control of memory allocation, I/O ac- 
cess, devices, and error processing. 

MEMORY ALLOCATION 

The memory needs of a program are specified to the monitor by the .SET- 
TOP request. When loaded, a program occupies the memory specified by its 
image created at link time. To obtain more memory, a .SETTOP request is 
executed, with RO containing the highest address desired. The monitor re- 
turns the highest address available. Resident handlers or foreground jobs 
can prevent all the memory that is desired from being available to the 
program. If the memory requirements of the running program permit, the 
monitor retains the User Service Routine (USR) in memory, which reduces 
swapping. Otherwise, the monitor will automatically remove the USR from 
memory and then swap part of the user program to the swap file called 
SWAP.SYS on the system device whenever the USR must be reloaded to 
process a request. The .SETTOP request then allows you to determine how 
much memory is available and to control monitor swapping characteristics. 
See the .SETTOP programmed request in Chapter 2 for special optional 
features provided in an extended memory environment. Additional infor- 
mation on the .SETTOP request is also given in the RT-11 Software Sup- 
port Manual. 

If a program needs so much memory that the USR must swap, swapping 
will automatically occur whenever a USR call is made. However, if a pro- 
gram knows what file operations are necessary, and if these operations can 
be consolidated and performed at one time, the efficiency of the system can 
be enhanced in the following manner: request the USR to be swapped in, 
have it remain resident while a series of consecutive USR operations is 
performed, then swap the USR out when the sequence of operations is 
completed. 
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Three programmed requests control USR swapping. The request .LOCK 
causes the USR to be made resident for a series of file operations. It can 
operate by: (1) requiring a portion of your program to be written to the 
swap blocks prior to reading in the USR; (2) only requiring a fresh copy of 
the USR if the USR buffer is overwritten; or (3) not requiring the USR to be 
read in if it finds the USR intact. The request .UNLOCK swaps your pro- 
gram back in if it was swapped out, and the USR is overwritten; otherwise, 
no swapping occurs. The request .TLOCK makes the USR resident in 
foreground/background programs, but only if the USR is not currently serv- 
icing another job's file requests at the time the .TLOCK request is issued. 
This check prevents a job from becoming blocked while the USR is process- 
ing another job's request. When a .TLOCK succeeds, the USR is ready to 
perform an operation immediately. In a single-job environment, the 
.TLOCK request performs exactly like the .LOCK request. 

RT-11 provides 16(decimal) channels as part of the job's impure 
area — that is, 16 files can be active at one time. Up to 255(decimal) 
channels can be activated with the .CDFN request. This request sets aside 
memory inside the job area to provide the storage required for the status 
information on the additional channels. Once the .CDFN request has been 
executed, as many channels as specified can be active simultaneously. Use 
the .CDFN request during the initialization phase of your program. The 
keyboard monitor command CLOSE does not work if you define new chan- 
nels with the .CDFN programmed request. 

The .CNTXSW request allows the job to add memory locations to the list of 
items to be context-switched. The request itself does not cause a context 
switch to occur. 

INPUT/OUTPUT ACCESS 

Each pending I/O, message, or timer request must be placed into one of the 
monitor queues. These are then processed by the monitor on a first-in first- 
out basis, by job priority, or by time of expiration. In RT-11, all I/O trans- 
fers are queued to allow asynchronous processing of the request. A queue is 
a list of elements, each element being seven words long (ten words [deci- 
mal] long when using the extended memory monitor). When your program 
issues a data transfer programmed request, the information specifying the 
transfer is stored by the monitor in a queue element. This information is 
passed to the device handler, which then processes the I/O transfer. 

Each job, whether background or foreground, initially has only a single 
queue element available. Additional queue elements may be set aside with 
a .QSET request. The .QSET request declares where in memory the addi- 
tional queue elements will go and how many elements there will be. If you 
do not include a .QSET request in your program, the monitor uses the 
queue element set aside in the job's impure area. In this case, since only one 
element is available for each job, all operations would be synchronous. That 
is, any request issued when the available queue element list is empty has 
to wait for that element to become free. The number of queue elements 
necessary equals the number of asynchronous operations pending at any 
time. 
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DEVICES 

The .DEVICE request turns off any special devices that are being used by 
the running program upon program termination. This request (available 
only in FB or XM) allows you to specify a set of device control register 
addresses and a value to be set in each register on job exit. When a job is 
terminated — either normally, by an error condition, or by a 
CTRL/C — the specified values are set in the specified locations. 

In SJ, a hard reset is done at .EXIT or CTRL/C. This clears all devices. 

Loading a background job with a GET, R, or RUN command, or loading a 
foreground or system job with a FRUN and SRUN command, respectively, 
alters most locations in the vector area to 476. RT-11 automatically 
prevents alteration of all locations used by the system, such as the clock, 
the console terminal, and all vectors used by handlers that are loaded. If a 
foreground job in a foreground/background environment accesses a device 
directly through an in-line interrupt service routine, the foreground job 
must notify the monitor that it must have exclusive use of the vectors. You 
use the .PROTECT programmed request to allow the foreground job to gain 
exclusive use of a vector. The .PROTECT request can also be used by either 
the foreground or background job, prior to setting the contents of a vector, 
to test whether the vectors are already controlled by a job. This serves as 
further protection against jobs interfering with each other. An .UNPRO- 
TECT programmed request relinquishes control of a vector, making the 
vector available to both the background and foreground jobs. 

The request .SPFUN is available for performing special functions on de- 
vices such as magnetic tape. .SPFUN requests are used for such functions 
as rewind or space-forward operations. 

ERROR PROCESSING 

During the course of program execution, errors can occur that cause the 
monitor to stop the program and print a MON-F error message. Examples 
include directory I/O errors, monitor I/O errors on the system device, or I/O 
requests to nonexistent devices. Some programs cannot afford to allow the 
monitor to abort the job because of such errors. For example, in the case of 
RT-11 multi-user BASIC, a directory I/O error affecting only one of the 
users should not cause the whole program to abort. For such applications, a 
pair of requests is provided, .HERR and .SERR. A .HERR request (normal 
default) indicates that the monitor will handle severe errors and stop the 
job. A .SERR request causes the monitor to return most errors to your 
program in byte 52 for appropriate action. 

In addition to processing I/O errors through .HERR and .SERR requests, 
you can also handle certain fatal errors through the .TRPSET or .SFPA 
requests. You use these requests to prevent your program from aborting 
due to a trap to location 4 or lO(octal), or to the exception traps of the 
Floating Point Processor (FPP) or Floating Point Instruction Set (FIS). A 
.TRPSET request specifies the address of a routine that the monitor enters 
when a trap to location 4 or 10 occurs. A .SFPA request specifies the ad- 
dress of a floating-point exception routine that is called when an exception 
trap occurs. 
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1.1.3.2 Examining System Information and Reporting Status — Several pro- 
grammed requests interrogate the system for specific details about a device 
or file that your program may be using. 

The .DATE request obtains the system date, which then can be printed on a 
report or entered as a data record in a file. The time-of-day can be obtained 
with a .GTIM request and used in the same way. A program can set the 
system date and/or time by using the .SDTTM programmed request. 
Changing the date or time has no effect on any outstanding mark time or 
timed wait requests. 

With a .GTJB request you can obtain information on whether the job is 
running in the foreground or background, the memory limits of the job, the 
virtual high limit for a job created with the linker /V option (XM only), the 
unit number of the job's console terminal (if you are using the multitermi- 
nal feature), the address of the job's channel area, the address of the job's 
impure area, and the job's logical job name (if you are using a monitor with 
the system job feature). 

Status information on a file — such as its starting block, its length, and 
the device it is located on — can be obtained with a .CSTATUS request. 
Status information on a device — such as its block length and controller- 
assignment number — can be obtained with a .DSTATUS request. 

The .MTGET and .MTSTAT programmed requests provide multiterminal 
status information when the multiterminal feature is being used. 

The programmed requests .MFPS and .MTPS read the priority bits and set 
the priority and T-bits in the processor status word (PSW). These requests 
allow a program to run without change on any processor from an LSI-11 to 
a PDP-11/60. 

1.1.3.3 Command interpretation — Two of the most useful programmed re- 
quests are .CSIGEN and .CSISPC. These requests call the Command String 
Interpreter (CSI), which is part of the USR. They are used to process stand- 
ard RT-11 command strings in the following general form: 

*Dev: Output/Option = Dev:Input/Option 

The asterisk is printed on the terminal by the monitor. The RT-11 system 
programs use the same command string (see the RT-11 System Utilities 
Manual). 

The .CSIGEN request analyzes the string for correct syntax, automatically 
loads the required device handlers into memory, opens the files specified in 
the command, and returns to your program with option information. Thus, 
with one request, a language processor such as the FORTRAN compiler is 
ready to input from the source files and output the listing and binary files. 
You can specify options in the command string to control the operation of 
the language processor. The .CSIGEN request uses channels through 2 to 
accommodate three output file specifications and channels 3 through 10(oc- 
tal) to accommodate six input file specifications. 
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The .CSISPC request provides you with the services of the command proces- 
sor, but allows you to do your own device and file manipulation. When you 
use .CSISPC, the CSI obtains a command string, analyzes it syntactically, 
places the results in a table, and passes the table to your program for 
appropriate action. 

The .GTLIN request obtains one line of input at a time instead of one 
character. These three requests support the indirect file function and allow 
your program to obtain one line at a time from an indirect file. Thus, if your 
program was started through an indirect file, the line is taken from the 
indirect file and not the terminal. The .GTLIN request has an optional 
argument which forces input to come from the terminal. The feature is 
useful if your program requires information which can be supplied only at 
run time. 

1.1.3,4 File Operations — A device handler is the normal RT-11 interface 
between the monitor and the peripheral device on which file operations are 
performed. The console terminal handlers (in FB and XM) and the interjob 
message handlers are part of the resident monitor and require no attention 
on your part. All other device handlers are loaded into memory with either 
a .FETCH request from the program or a LOAD command from the key- 
board before any other request can access that device. Section 1.1.3.5 of this 
manual describes the use of programmed requests for performing I/O opera- 
tions. The RT-11 Software Support Manual describes how to write device 
handlers for RT-11. 

Once the handler is in memory, a .LOOKUP request can locate existing 
files and open them for access. New files are created with an .ENTER 
request. Space for the file can be defined and allocated as: 

1. One-half the size of the largest unused space or all of the second largest 
space, whichever is larger (the default) 

2. A space of a specific size 

3. As much space as possible 

The way the system allocates the space depends upon the parameter speci- 
fied by you as the file size argument of the .ENTER request or specified in a 
.CSIGEN command string. 

When file operations are completed, a .CLOSE request makes the new file 
permanent in the directory. A .PURGE request can free the channel with- 
out making the file permanent in the directory. Existing permanent files 
can be renamed with a .RENAME request or deleted with a .DELETE 
request. 

Two other requests, .SAVESTATUS and .REOPEN, add to the flexibility of 
file operations. The .SAVESTATUS request stores the current status of a 
file that has been opened with a .LOOKUP request and makes the file 
temporarily inactive, thus freeing the channel for use by another file. The 
.REOPEN request causes the inactive file to be reactivated on the specified 
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channel, and I/O continues on that channel. In this manner, you can open 
more files than there are channels. If, in addition, you lock the USR in 
memory, you can open all the files your job needs while maintaining system 
swapping efficiency. The procedure is: 

1. Lock the USR in memory, and open the files that are needed. 

2. Issue the .SAVESTATUS request. 

3. Release the USR. 

4. Issue a .REOPEN request each time a file is needed. 

5. Lock USR, and use the .CLOSE request to make the files permanent. 

Because a .REOPEN request does not require any I/O, all USR swapping 
and directory motion can be isolated in the initialization code for an appli- 
cation, improving program efficiency. 

The creation date and protection status of a file can be modified by using 
the .SFDAT and .FPROT requests, respectively. 

The .SFDAT request allows you to change the date that appears in a file's 
directory entry listing. You may want to do this for a file that you update in 
place, for example, or if the original creation date was in error. 

The .FPROT request protects a file against deletion, or removes protection 
so that a file can be deleted by a .DELETE, .ENTER, or .RENAME request. 
The contents of a protected file are not protected against modification. 

1.1.3.5 Input/Output Operations — You can perform I/O in three different 
modes: 

• synchronous 

• asynchronous 

• event-driven 

These modes allow you to optimize the overlap of CPU and I/O processing. 

The programmed requests .READW and .WRITW perform synchronous 
I/O — that is, the instruction following the request is not executed until 
the I/O transfer is completely finished; thus the program and the I/O pro- 
cess are synchronized. 

The program requests .READ, .WRITE, and .WAIT perform asynchronous 
I/O — that is, the .READ or .WRITE request adds the transfer request to 
the queue for the device; if the device is inactive, the transfer begins; con- 
trol returns to the user program before the transfer is completed. The 
.WAIT programmed request, however, blocks the program until the trans- 
fer is completed. This allows the I/O operation to be completed before any 
further processing is done. Asynchronous I/O is most commonly used for 
double buffering. 



1-20 Introduction to Advanced RT-11 Programming 



Program requests such as .READC and .WRITC perform event-driven 
I/O — that is, they initiate a completion routine when the transfer is fin- 
ished. 

Event-driven I/O is practical for conditions where system throughput is 
important, where jobs are divided into overlapping processes, or where pro- 
cessing timings are random. The last condition is the most attractive case 
for using event-driven I/O because processor timing may range up to infin- 
ity in that a process is never completed. 

Since the completion routine is essential to event-driven I/O, the next sec- 
tion presents general guidelines for writing completion routines. 

COMPLETION ROUTINES 

Completion routines are part of your program. They execute following the 
completion of some external operation, interrupting the normal program 
flow. On entry to an I/O completion routine. Register contains the con- 
tents of the Channel Status Word and Register 1 contains the channel 
number for the operation. The carry bit is not significant. 

Completion routines are handled differently, depending on whether the 
program is being run under the SJ monitor or the FB and XM monitors. 
Under the SJ monitor, completion routines are totally asynchronous and 
can interrupt each other. An interrupted completion routine is resumed 
when the interrupting routine is finished. Unlike completion routines run 
under FB and XM monitors, which are serialized and run at priority 0, 
completion routines run under an SJ monitor are nested. In addition, they 
execute not at priority 0, but at the same priority as the device whose 
interrupt scheduled them. For example, the completion routine resulting 
from a .WRITC programmed request to device TT: runs at priority 4. Com- 
pletion routines from timer requests run at the same priority as the system 
clock. This is particularly important on LSI-11 and PDP 11/03 systems that 
have only two interrupt levels, ON and OFF, because clock interrupts may 
be lost while lengthy completion routines execute. Under the FB and XM 
monitors, completion routines do not interrupt one another. Instead, they 
are queued, and the next routine is not entered until the first is completed. 

If the foreground job is running and a foreground I/O transfer completes 
and wants a completion routine, that routine is entered immediately if the 
foreground job is not already executing a completion routine. If it is in a 
completion routine, that routine continues to termination, at which point 
other completion routines are entered in a first-in first-out order. If the 
background job is running (even in a completion routine) and a foreground 
I/O transfer completes with a specified completion routine, execution of the 
background job is suspended and the foreground routine is entered immedi- 
ately. 

Also under the FB and XM monitors, it is possible to request a completion 
routine from an in-line interrupt service routine through a .SYNCH pro- 
grammed request. This allows the interrupt service routine to issue other 
programmed requests to the monitor. 
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Restrictions that must be observed when writing completion routines are as 
follows: 

1. Requests that require the USR must not be issued within a completion 
routine. A fatal monitor error is generated if the USR is called from a 
completion routine. 

2. Completion routines should never reside in memory space that is used 
for the USR, since the USR can be interrupted when I/O terminates and 
the completion routine is entered. If the USR has overlaid the routine, 
control passes to a random place in the USR, with a HALT or error trap 
being the likely result. 

3. Registers other than RO and Rl must be saved upon entry to completion 
routines and restored upon exiting. Registers cannot transfer data be- 
tween the mainline program and the completion routine. 

4. Under the XM monitor, completion routines must remain mapped 
while the request is active and the routine can be called. 

5. The completion routine must exit with an RTS PC instruction because 
the routine was called from the monitor with a JSR PC,ADDR, where 
ADDR is the user-supplied entry point address. If you exit completion 
routines with an .EXIT request, your job will abort. An exit from a 
completion routine in FB or XM can be done by using an .SPCPS re- 
quest to change the mainline PC to point to an .EXIT in the main code. 
As soon as all completion routines are done, the exit will be executed. 

6. Under the XM monitor, completion routines scheduled as a result of a 
.SYNCH run in kernel mapping, not user mapping. 

Frequently, a program's completion routine needs to change the flow of 
control of the mainline code. For example, you may wish to establish a 
schedule among the various tasks of an application program after a certain 
time has elapsed, or after an I/O operation is complete. Such an application 
needs to redirect the mainline code to a scheduling subroutine when the 
application's timer or read/write completion routine runs. The .SPCPS pro- 
grammed request, which can only be used in a foreground/background or 
extended memory environment, saves the mainline code program counter 
and processor status word, and changes the mainline code program counter 
to a new value. If the mainline code is performing a monitor request, that 
request finishes before rerouting can occur. 

TERMINAL INPUT/OUTPUT 

Several programmed requests are available to provide an I/O capability 
with the console terminal: a .TTYIN request obtains a character from the 
console; a .TTYOUT request prints a character on the terminal; long 
strings of characters — even multiple lines — are output with the 
.PRINT request. Programs can also issue .TTINR and .TTOUTR requests, 
which indicate that a character is not available or that the output buffer is 
full. The program can then resume operation and try again at a later time. 
A .RCTRLO request forces the terminal output to be reactivated after a 
CTRL/0 has been typed to suppress it, so that urgent messages will be 
printed. 
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You can use the .TTYIN/.TTINR requests in special (single-character) 
mode by setting bit 12 of the Job Status Word. See the .TTYIN programmed 
request for a description of special mode. 

MULTITERMINAL REQUESTS 

The RT-11 multi terminal feature allows your program to perform 
input/output on up to 17 terminals. Several programmed requests allow 
you to perform I/O on these terminals. Before issuing any of these pro- 
grammed requests to a terminal, you must issue the .MTATCH request, 
which reserves the specified terminal for exclusive use by your program. 
The terminal cannot then be used by any other job until you issue the 
.MTDTCH request to detach the terminal. 

The .MTIN request returns to a program characters that are typed at the 
terminal, while the .MTOUT and .MTPRNT requests send characters to a 
terminal. These requests are analogous to the .TTYIN, .TTYOUT, and 
.PRINT requests. Note that the .TTYIN/.TTINR, .TTYOUT/.TTOUTR, and 
.PRINT requests can only be used with the console terminal. 

You can set terminal and line characteristics with the .MTSET request. 
You provide a four-word status block that contains the terminal status 
word, the character of the terminal requiring fillers and the number of 
fillers required for this character, the width of the carriage (80 characters 
by default), and system terminal status. The status of a terminal can be 
obtained by issuing the .MTGET request. The .MTSTAT request provides 
multi terminal system status information. 

1.1.3.6 Foreground/Background Communications — Communication between 
foreground and background jobs is obtained through the programmed re- 
quests .SDAT and .RCVD. These requests also have three modes (synchro- 
nous, asynchronous, and event driven) that allow transfer of buffers be- 
tween the two jobs as if I/O were being done. The sending job treats a 
.SDAT request as a write, and the receiving job treats .RCVD as a read. In 
the case of .RCVD requests, the receiving buffer must be one word longer 
than the number of words expected. When the data transfer is completed, 
the first word of the buffer contains the number of words actually sent. 

Jobs receiving messages can be activated when messages are sent through 
.RCVDC completion routines, while the sending jobs use .SDATC comple- 
tion routines. The .MWAIT request is used for synchronizing message re- 
quests. It is similar to the .WAIT request that is used for normal I/O. 

If you want one job in a foreground/background environment to read or 
write data in a file opened by the other job, use the .CHCOPY request. For 
example, when the background job is processing data that is being collected 
by the foreground job, the .CHCOPY request allows you to obtain channel 
information from the foreground job and to use that channel information to 
control a read or write request. 

The foreground/background monitor always causes a context switch of criti- 
cal items such as machine registers, the job status area, and floating-point 
processor registers when a different job is scheduled to run because it has a 
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higher priority, or because the current job is blocked and a lower priority 
job is runnable. When the monitor saves a job's context, it saves the job- 
dependent information on the job's stack so that this information can be 
restored when the job is runnable again. 

1.1.3.7 Timer Support — Timer support by the monitor is provided through 
the .MRKT request. With the .MRKT request, you specify the address of a 
routine that is to be entered after a specified number of clock ticks. Like I/O 
completion routines, .MRKT routines are asynchronous and independent of 
the main program. After the specified time elapses, the main program is 
interrupted, the timer completion routine executes, and control returns to 
the interrupted program. 

Pending .MRKT requests — as many as the queue can hold — are identi- 
fied by number. Pending timer requests can be canceled with a .CMKT 
request. .MRKT requests are normally used as a scheduling tool where jobs 
are scheduled on the basis of clock events, detected by timer completion 
routines. 

A job can be suspended for a specified time interval with a .TWAIT request. 
For example, the .TWAIT request will allow a compute-bound job to relin- 
quish CPU time to the rest of the system, permitting other jobs to run. 

1.1.3.8 Program Termination or Suspension — Many jobs come to an execu- 
tion point where there is no further processing necessary until an external 
event occurs. In the FB or XM environment such a job can issue a .SPND 
request to suspend the execution of that job. While the foreground job is 
suspended, the background job runs. When the desired external event oc- 
curs, it is detected by a previously requested completion routine, which 
executes a .RSUM request to continue the job at the point where it was 
suspended. 

When a job is ready to terminate or reaches a serious error condition, it can 
reset the system with the .SRESET and .HRESET requests. .SRESET is a 
soft reset. That is, the monitor data base for the job is reinitialized, but 
queued I/O is allowed to run to completion. .HRESET is a hard reset where 
all I/O for the job is stopped (by a RESET instruction in the SJ monitor or 
by calls to the handlers in an FB environment). 

Use the programmed request .EXIT in a background job to return control to 
the keyboard monitor by causing program termination. If Register con- 
tains a zero upon execution of this request, a hard reset is performed, and 
the commands REENTER, CLOSE, and START are disabled. If Register 
contains a non-zero value upon exit from your program, a soft reset is done, 
and these commands are not disabled. In a foreground job, an .EXIT pro- 
grammed request stops the job but does not return control to the keyboard 
monitor. The job can be removed from memory by the UNLOAD command. 

You may initiate the execution of another program with a .CHAIN request 
from a background job. Files remain open across a .CHAIN request and 
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data is passed in memory to the chained job, so that it can adjust process- 
ing. In FORTRAN, channel information is stored in the job's impure area, 
and this information is not preserved across a .CHAIN request. Thus, close 
any channels in the first program, and reopen them in the program being 
chained to. 

1 .1 .3.9 System Job Communications — System job support allows communi- 
cations between any two jobs in the system. The background job, designated 
by the logical job name 'B', and the foreground job, designated by the logi- 
cal job name 'F', can send and receive messages between each other by 
using the .RCVD and .SDAT programmed requests. 

All jobs (that is, background, foreground, and system jobs) can communi- 
cate with each other by using the Message Handler (MQ). The MQ handler 
performs like an ordinary RT-11 device handler in the way it accepts and 
dispatches I/O requests from the queued I/O system. This permits .READ 
and .WRITE requests to send messages between any two jobs as if they 
were data transfers to files. Both the sending and receiving job must issue a 
.LOOKUP request on a channel and use 'MQ' as the device specification 
and the logical job name of the job with which they are communicating as 
the file specification. In the case of .READ requests, the receiving buffer 
must be one word longer than the number of words expected. When the 
data transfer is completed, the first word of the buffer contains the number 
of words actually sent (identical to the .RCVD requests). This does not 
apply to the .WRITE requests; the first word of the sending buffer is the 
first word of the message to be sent. Note that the Message Handler (MQ) 
can also be used under the distributed FB monitor; it does not require the 
system job special feature. 

Care should be taken when assigning logical job names to system jobs. 
Programmed requests such as .LOOKUP, .CHCOPY, and .GTJB must use 
the job's current logical job name (see the RT-11 System User's Guide). 

1.1.3.10 Extended IVIemory Functions — The RT-11 extended memory (XM) 
monitor permits MACRO programs to access extended memory by mapping 
their virtual addresses to physical locations in memory. This is done in 
conjunction with a hardware option called the Memory Management Unit 
that converts a 16-bit virtual address to an 18- or 22-bit physical address. 

You access extended memory in a program through programmed requests. 
In accessing extended memory, you must first establish window and region 
definition blocks. Next, you must specify the amount of physical memory 
the program requires and describe the virtual addresses you plan to use. Do 
this by creating regions and windows. Then, associate virtual addresses 
with physical locations by mapping the windows to the regions. You can 
remap a window to another region or part of a region, or you can eliminate 
a window or a region. Once the initial data structures are set up, you can 
manipulate the mapping of windows to regions that best meet your require- 
ments. 
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There are four types of extended memory programmed requests: 

1. Window requests 3. Map requests 

2. Region requests 4. Status requests 

The window and region requests have their own data structures. RT-11 
provides the macro .WDBBK to create a window definition block and the 
macro .RDBBK to create a region definition block. Both macros automati- 
cally define offsets and bit names. Two other macros, .WDBDF and 
.RDBDF, define only the offsets and bit names. 

The programmed request .CRAW is used to create a window. To eliminate a 
window, use the .ELAW request. A region is created using the .CRRG 
request. You return a region to the free list of memory with the .ELRG 
request. 

You map a window to a region with the .MAP request. If a window is 
already mapped to a region, this window is unmapped and the new one is 
mapped. Use the .UNMAP request to unmap a window. You obtain the 
mapping status of a window with the .GMCX request. 

Certain programmed requests are restricted when they are in an extended 
memory environment. These programmed requests and their restrictions 
are as follows: 

.CDFN All channels must be in the lower 28K of memory (but 

not in the PARI region, 20000-37776 octal). 

.QSET All queue elements must be lO(decimal) words long and 

in the lower 28K of memory (but not in the PARI re- 
gion, 20000-37776 octal). 

.SETTOP Effective only in the virtual address space that is 
mapped at the time the request is issued, unless the job 
was linked with the /V option (see the RT-11 System 
Utilities Manual). 

.CNTXSW Not usable in virtual jobs. 

Detailed information on programmed requests in an extended memory en- 
vironment is given in the RT-11 Software Support Manual. 

1.1.3.11 Interrupt Service Routines — The system macro library (SYS- 
MAC.SML) contains some macros that are not programmed requests, but 
are used like programmed requests in interrupt service communication to 
the monitor. The first macro call in every interrupt routine is .INTEN, 
which causes the system to use the system stack for interrupt service and 
allows the monitor scheduler to make note of the interrupt. If device service 
is all the routine does, .INTEN is the only call it need make. If you need to 
issue one or more programmed requests, such as .READ or .WRITE from 
the interrupt service routine, you must issue the .SYNCH call. The .INTEN 
call described above switches execution to the system state, and since pro- 
grammed requests can only be made in the user state, the .SYNCH call 
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handles the switch back to the user state. The code following the .SYNCH 
call executes as a completion routine. When the .SYNCH is finished, the 
completion routine can execute programmed requests, initiate I/O, and re- 
sume the mainline code. The first word after the .SYNCH call is the return 
address on error, while the second word is the return on success. The 
RT-11 Software Support Manual contains a detailed description of inter- 
rupt service routines. 

1.1.3.12 Device Handlers — The system macro library (SYSMAC.SML) con- 
tains several macros that simplify the writing of a device handler. A device 
handler is divided into several sections. These sections are as follows: 

• Preamble section • Interrupt service section 

• Header section • I/O completion section 

• I/O initiation section • Termination section 

The .DRDEF macro is used near the beginning of your device handler, and 
performs much of the work in the preamble section. The .DRBEG macro 
sets up the first five words in the header section, stores information in 
block of the handler file, and creates some global symbols. The .DRAST 
macro sets up the interrupt entry point and the abort entry point in the 
interrupt service section, and lowers the processor priority. The .DRFIN 
macro generates the instructions for the jump back to the monitor at the 
end of the handler I/O completion routine. The .DREND macro generates 
handler termination code. The .DRBOT macro sets up the primary driver. 
A primary driver must be added to a standard handler for a data device to 
create a system device handler. The .DRSET macro sets up the option table 
for the SET command in block of the device handler file. The .DRVTB 
macro sets up a table of vectors for devices that require more than one 
vector. 

Each of the device handler macros is described in Chapter 2. The RT-11 
Software Support Manual details the use of these macros in writing a de- 
vice handler. 

1.1.4 Compatibility With Previous RT-11 Versions 

Programmed requests were implemented differently in each major release 
of RT-11. The following sections outline the changes that were made to the 
programmed requests from version to version. 

1.1.4.1 Version 1 Programmed Requests — Programmed requests provided 
with the first release of RT-11, such as .READ and .WRITE, were designed 
for a single-user, single-job environment. As such, they differ significantly 
from the programmed requests of the later versions. For Version 1 requests, 
arguments were pushed on the stack instead of being stored, as they are 
presently, in an argument block. The channel number was limited to the 
range through 17(octal), while later versions can allocate an additional 
number of channels. Also, no arguments could be omitted in the macro call. 
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Programs written for use under Version 1 assemble and execute properly 
under Versions 3, 4, and 5 when the ..VI.. macro call is used. The ..VI.. 
macro call causes all Version 1 programmed requests to expand exactly as 
they did in Version 1. The ..V2.. macro call expands all requests in Version 
2 format. However, it is to your advantage to convert Version 1 and Version 
2 programs to the current format for programmed requests (see Section 
2.7). Future versions of RT-11 may no longer support the older formats. 

1.1.4.2 Version 2 Programmed Requests — The release of RT-11 Version 2 
included new programmed requests and a different way of handling argu- 
ments. The new programmed requests reflected RT-ll's ability to run a 
foreground job as well as a background job. They included requests to 
suspend/resume the foreground job and to share messages and data be- 
tween the two jobs. 

Arguments in Version 2 programmed requests were stored in an argument 
block instead of on the stack. Another difference in Version 2 was that 
arguments could be omitted from macro calls. If the Area 
argument — that is, the pointer to the argument block — was omitted, 
the macro assumed that RO pointed to a valid argument block. If any of the 
optional arguments were not present, the macro placed a zero in the argu- 
ment block for the corresponding argument. Version 1 programmed re- 
quests were modified to incorporate these changes, and the ..VI.. macro was 
provided to allow Version 1 programmed requests to execute under Version 
2 without further modification. 

Programs written for use under Version 2 assemble and execute properly 
under Versions 3 and 4 when the ..V2.. macro call is used. The ..V2.. macro 
call causes all programmed requests prior to Version 3 to expand in Version 
2 format. 

1.1.4.3 Version 3 Programmed Requests — The programmed requests for 
Version 3 provide means for user programs to access regions in extended 
memory and to use more than one terminal. The chief difference between 
Version 2 and Version 3 programmed requests is the way in which omitted 
arguments are handled. In Versions 3, 4, and 5, blank arguments in the 
macro calls do not cause zeros to be entered into the argument block, but 
leave the corresponding argument block entry for the missing argument 
untouched. 

This change can have a significant impact on user programs. If an argu- 
ment block within a program is to be used many times for similar calls, you 
can save instructions by setting up the argument block entries only once (at 
assembly or run time), and leaving the corresponding fields blank in the 
macro call. 

However, you should keep in mind that you may not substitute zeroes for 
missing fields. Programs written with this assumption operate incorrectly 
and exhibit a wide range of symptoms that can be hard to diagnose. There- 
fore, you must write the necessary instructions to fill the argument block if 
a programmed request is issued with fields left blank in the argument list. 

Programmed requests from previous versions were modified to incorporate 
this change, and the ..V2.. macro call was provided so that Version 2 pro- 
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grams could execute properly under Version 3 without further modifica- 
tion. 

1.1.4.4 Version 4 Programmed Requests — Certain programmed requests 
have taken on additional functions to support the system job feature. These 
programmed requests and their additional functions follow: 

Added Function 



Programmed Request 

.GTJB 
.CHCOPY 



Returns logical job name. 

May specify logical job name. 

LOOKUP Opens message channel to any job; issues 

.READ/C/W, .WRITE/C/W, and .WAIT re- 
quests to communicate between jobs. 

1.1.4.5 Version 5 Programmed Requests — Version 5 added several new 
programmed requests and modified others. The requests added for Version 
5 are .ABTIO, .FPROT, PEEK, .POKE, .PVAL, and .SFDAT. Although the 
XM monitor was expanded to support 22-bit Q-bus addressing, from a pro- 
gram's point of view the extended memory programmed requests are un- 
changed from Version 4. Channel number 377 is now reserved for system 
use and is always unavailable to user programs. The programmed requests 
which have changed between Version 4 and Version 5 are summarized 
below: 



Programmed Request 

.CSTAT 
.TWAIT 
.FETCH 
.GTLIN 



Added Function 

Available under SJ monitor. 

Available under SJ monitor. 

Available under XM monitor. 

Optional argument to force terminal in- 
put. 



1.1.5 Programmed Request Conversion 

The previous sections describe the modified format of programmed requests 
that were developed after those of Version 1. This section describes the 
conversion process from the Version 1 format to Version 3. 
1 .1 .5.1 Macro Calls Not Requiring Conversion — Version 1 macro calls that do 
not require any conversion are as follows: 



CSIGEN 


.LOCK 


.SRESET 


CSISPC 


.PRINT 


.TTINR (Note 2) 


DATE 


.QSET 


.TTOUTR (Note 2) 


.DSTATUS 


.RCTRLO 


.TTYIN 


•EXIT 


.RELEAS 


.TTYOUT 


.FETCH 


.SETTOP (Note 1) 


.UNLOCK 


.HRESET 







Note 1: Provided that location 50 is examined for the maximum value. 
Note 2: Except in FB or XM systems. 
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1.1.5.2 Macro Calls That Can Be Converted — Version 1 macro calls that can 
be converted are as follows: 

.CLOSE .RENAME 

.DELETE .REOPEN 

.ENTER .SAVESTATUS 

.LOOKUP .WAIT 

.READ .WRITE 

The general format of the ..VI.. system macro is 

.PRGREQ Chan,Argl,...,Argn 

In this form, Chan is an integer between and 17(octal) and is not a 
general assembler argument. The channel number is assembled into the 
EMT instruction itself. The arguments Argl through Argn are either 
moved into RO or pushed on the stack. 

The ..V2.. equivalent of the above call is 

•PRGREQ Area,Chan,Argl,...,Argn 

In this form, the Chan argument can be any legal assembler argument and 
can be in the range from to 377(octal). Area points to an argument block 
where the arguments Argl through Argn will be placed. 

For example, consider a .READ programmed request in both forms: 

Version 1: .READ 5 (#BUFF »«25e. .BLOCK 

Version 2: .READ *AREA .«5 t«BUFF t#Z5B. .BLOCK 



AREA: .WORDO 5CHANNEL/FUNCTI0N CODE HERE 

WORD iBLOCK NUMBER HERE 
WORD !BUFFER ADDRESS HERE 
WORD iWORD COUNT HERE 
WORD 5A 1 GOES HERE 

Thus, the difference in the two macro calls is that Version 2 declares the 
channel number as a legal assembler argument and adds an Area argu- 
ment. 

Table 1-3 shows a complete list of conversions for the programmed requests 
that can be converted. Version 1 and Version 2 formats are given. In Ver- 
sions 3 and later, this function is performed automatically. The arguments 
shown inside the square brackets ([ ]) are optional. Refer to the appropriate 
section in Chapter 2 for more details on each request. 



1-30 Introduction to Advanced RT-11 Programming 



Table 1-3: Programmed Request Conversions (Version 1 to 
Version 2) 



Version 


Programmed Request 


VI: 
V2: 


.DELETE chan.dblk 

.DELETE area,chan.,dblk[, count] 


VI: 
V2: 


.LOOKUP chan,dblk 

.LOOKUP area,chan,dblk[,count] 


VI: 
V2: 


.EISJTKR chan,dblk[,length] 

.ENTER area,chan,dblk[,length[,count]] 


VI: 
V2: 


.RENAME chan,dblk 
.RENAME area,chan,dblk 


VI: 
V2: 


.SAVESTAT chan,cblk 
.SAVESTAT area,chan,cblk 


VI: 
V2: 


.REOPEN chan.cblk 
.REOPEN area,chan,cblk 


VI: 
V2: 


.CLOSE Chan 
.CLOSE Chan 


VI: 

V2: 


.READ/.READW chan,buff,wcnt,blk 
.READ/.READWarea,chan,buff,wcnt,blk 


VI: 
V2: 


.READC chan,buff,wcnt,crtn,blk 
.READC area,chan,buff,wcnt,crtn,blk 


VI: 
V2: 


.WRITE/. WRITW chan,buff,wcnt,blk 
.WRITE/. WRITWarea,chan,buff,wcnt,blk 


VI: 
V2: 


.WRITC chan,buff,wcnt,crtn,blk 
.WRITC area,chan,buff,wcnt,crtn,blk 


VI: 
V2: 


.WAIT chan 
.WAIT chan 



Several important features of Version 3 calls to be kept in mind when using 
them are as follows: 

1. Version 3 calls require the area argument, which points to the area 
where the other arguments will be (unless RO already points to it and 
the first word is set up). 

2. Enough memory space must be allocated to hold all the required argu- 
ments. 

3. The chan argument must be a legal assembler argument, not just an 
integer between and 17(octal). 

4. Blank fields are permitted in the Version 3 calls. Any field not specified 
(left blank) is not modified in the argument block. 
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1.1.6 Programmed Request Summary 

Many programmed requests operate only in a specific RT-11 environment, 
such as under a foreground/background monitor or when using a special 
feature such as multiterminal operation. Table 1-4 lists the programmed 
requests that can be used in all RT-11 environments, including multiter- 
minal operation. Table 1-5 lists the additional programmed requests that 
can be used under the foreground/background monitor and extended mem- 
ory monitor. The EMT and function code for each request are shown in 
octal. Although only the first six characters of the programmed request are 
significant to the Macro assembler, the longer forms are shown to provide a 
better understanding of the request function. Also, the purpose of each 
request is described. 

Macros that are used in interrupt service routines and in writing device 
handlers are listed since they are a part of the system macro library. 

Table 1-4 summarizes the programmed requests that work in all RT-11 
environments. The programmed requests followed by (MT) work only under 
the multiterminal feature of RT-11. 

Table 1-4; Programmed Requests for AH RT-11 Environments 



Name 



EMT Code 



Purpose 



.ABTIO 


374 


13 


.CDFN 


375 


15 


.CHAIN 


374 


10 


.CLOSE 


374 


6 


.CMKT 


375 


23 



.CSIGEN 

.CSISPC 

.CSTAT 
.CTIMIO 

.DATE 

.DELETE 

.DRAST 

.DRBEG 

.DRBOT 



344 



345 



375 



374 
375 



27 



12 




Aborts I/O in progress on the specified channel 

Defines additional channels for I/O 

Chains to another program (in background job 
only) 

Closes the specified channel 

Cancels an unexpired mark time request (special 
feature in single-job environment) 

Calls the Command String Interpreter (CSI) in 
general mode 

Calls the Command String Interpreter (CSI) in 
the special mode 

Returns the status of the specified channel 

Used within a device handler as a macro call to 
cancel a mark time request (special feature) 

Moves the current date information into RO 

Deletes the file from the specified device 

Used with device handlers to create the asynchro- 
nous entry points to the handler 

Used with device handlers to create a five-word 
header, and .ASECT locations 52 through 60 

Used with system device handlers to set up the 
primary driver 



(continued on next page) 
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Table 1-4: Programmed Requests for All RT-11 Environments (Cont.) 



Name 



EMT Code 



Purpose 



•DRDEF 

.DREND 
.DRFIN 

.DRSET 
.DRVTB 



.DSTATUS 


342 


.ENTER 


375 


EXIT 


350 


.FETCH 


343 


.FORK 


— 



FPROT 


375 


43 


,GTIM 


375 


21 


.GTJB 


375 


20 


.GTLIN 


345 


— 


.GVAL 


375 


34 


.HERR 


374 


5 


.HRESET 


357 


— 



.INTEN 



.LOCK 



.LOOKUP 



346 



375 



Used with device handlers to set up handler 
parameters, call driver macros from the library, 
and define useful symbols 

Used with device handlers to generate the table of 
pointers into the resident monitor 

Used with device handlers to generate the code 
required to exit to the completion code in the resi- 
dent monitor 

Used with device handlers to create the list of SET 
options for a device 

Used with multivector device handlers to generate 
a table that contains the vector location, interrupt 
entry point, and processor status word for each de- 
vice vector 

Returns the status of a particular device 

Creates a new file for output 

Exits the user program and optionally passes a 
command to KMON 

Loads a device handler into memory 

Generates a subroutine call in an interrupt ser- 
vice routine that permits long but not critical pro- 
cessing to be postponed until all other interrupts 
are dismissed 

Sets or removes a file's protection 

Gets the time of day 

Gets parameters of a job 

Accepts an input line from either an indirect com- 
mand file or the console terminal 

Returns contents of a monitor fixed offset 

Specifies termination of a job on fatal errors 

Terminates I/O transfers and does a .SRESET op- 
eration 

Generates a subroutine call to notify the monitor 
that an interrupt has occurred, requests system 
state, and sets processor priority to the specified 
value 

Makes the monitor User Service Routine (USR) 
permanently resident until an .EXIT or .UN- 
LOCK is executed; the user program is swapped 
out, if necessary 

Opens an existing file for input and/or output via 
the specified channel; opens a message channel to 
a specified job 

(continued on next page) 
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Table 1-4; Programmed Requests for All RT-11 Environments (Cont.) 



Name 



EMT Code 



Purpose 



.MFPS 



.MRKT 



375 



.MTATCH (MT) 375 



.MTDTCH (MT) 375 



•MTGET (MT) 375 



.MTIN (MT) 



375 



.MTOUT (MT) 375 



.MTPRNT (MT) 375 



.MTPS 



.MTRCTO (MT) 375 



.MTSET (MT) 



375 



.MTSTAT (MT) 


375 


37 


.PEEK 


375 


34 


.POKE 


375 


34 


.PRINT 


351 


— 


.PURGE 


374 


3 


.PVAL 


375 


34 


.QELDF 






.QSET 


353 





.RCTRLO 


355 


_ 



.READ 



375 



— Reads the priority bits in the processor status 

word, but does not read the condition codes 

22 Marks time, that is, sets an asynchronous routine 

to be entered after specified interval (special fea- 
ture in single-job environment) 

37 Attaches a terminal for exclusive use by the re- 

questing job 

37 Detaches a terminal from one job and frees it for 
use by other jobs 

37 Returns the status of a specified terminal to the 

user 

37 Operates as a .TTYIN request for a multiterminal 

configuration 

37 Operates as a .TTYOUT request for a multitermi- 

nal configuration 

37 Operates as a .PRINT request for a multiterminal 

configuration 

— Sets the priority bits, condition codes, and T-bit in 

the processor status word 

37 Resets the CTRL/0 flag for the designated termi- 
nal 

37 Modifies terminal status in a multiterminal con- 

figuration 

Provides multiterminal system status 

Examines memory locations 

Changes memory locations 

Outputs an ASCII string terminated by a zero 
byte or a 200 byte 

Clears out a channel for reuse 

Replaces contents of a monitor fixed offset 

Used with device handlers to define offsets in the 
I/O queue element 

Increases the size of the monitor I/O queue 

Enables output to the terminal, overriding any 
previous CTRL/0 

10 Transfers data on the specified channel to a mem- 
ory buffer and returns control to the user program 
when the transfer request is entered in the I/O 
queue; no special action is taken upon completion 
of I/O 



(continued on next page) 
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Table 1-4: Programmed Requests for All RT-11 Environments (Cont.) 



Name 



EMT 



Code 



Purpose 



.READC 



375 



.READW 


375 


.RELEASE 


343 


.RENAME 


375 



.REOPEN 



375 



.SAVESTATUS 375 



,SCCA 


375 


35 


SDTTM 


375 


40 


SERR 


374 


4 


.SETTOP 


354 


— 


.SFDAT 


375 


42 


.SFPA 


375 


30 


.SPFUN 


375 


32 


.SRESET 


352 


— 


•SYNCH 







.TIMIO 



•TLOCK 



.TRPSET 



374 



375 



10 Transfers data on the specified channel to a mem- 

ory buffer and returns control to the user program 
when the transfer request is entered in the I/O 
queue; upon completion of the read, control trans- 
fers asynchronously to the completion routine 
specified in the .READC request 

10 Transfers data via the specified channel to a mem- 

ory buffer and returns control to the user program 
only after the transfer is complete 

— Removes a device handler from memory 

4 Changes the name of the indicated file to a new 
name; if this request is attempted when using 
magtape, the handler returns an invalid operation 
code 

6 Restores the parameters stored via a .SAVE- 
STATUS request and reopens the channel for I/O 

5 Saves the status parameters of an open file in user 
memory and frees the channel for use 

Enables intercept of CTRL/C commands 

Sets the system date and/or time 

Inhibits most fatal errors from aborting the cur- 
rent job 

Specifies the highest memory location to be used 
by the user program 

Changes a file creation date in a directory entry 

Sets user interrupt for floating-point processor ex- 
ceptions 

Performs special functions on magtape, cassette, 
diskette, and some disk devices 

Resets all channels and releases the device han- 
dlers from memory 

Generates a subroutine call that enables your pro- 
gram to perform programmed requests from 
within an interrupt service routine 

Generates a subroutine call in a handler to sched- 
ule a mark time request (special feature in all en- 
vironments) 

Indicates if the USR is currently used by another 
job and performs exactly as a .LOCK request in a 
single-job environment 

Sets a user intercept for traps to monitor locations 
4 and 10 



(continued on next page) 
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Table 1-4; Programmed Requests for All RT-11 Environments (Cont.) 



Name 



EMT Code 



Purpose 



.TTINR 


340 





.TTYIN 






.TTYOUT 


341 




.TTOUTR 






.TWAIT 


375 


24 


.UNLOCK 


347 


— 


..VI.. 








..V2.. 


— 


— 


•WAIT 


374 





-WRITC 


375 


11 



.WRITE 



.WRITW 



375 



375 



— Reads one character from the keyboard buffer 



Transfers one character to the terminal input 
buffer 

Suspends the running job for a specified amount of 
time 

Releases the USR after execution of a .LOCK and 
swaps in the user program, if required 

Provides compatibility with Version 1 format 

Provides compatibility with Version 2 format 

Waits for completion of all I/O on a specified chan- 
nel 

Transfers data on the specified channel to a device 
and returns control to the user program when the 
transfer request is entered in the I/O queue; upon 
completion of the write, control transfers asyn- 
chronously to the completion routine specified in 
the .WRITC request 

Transfers data on the specified channel to a device 
and returns control to the user program when the 
transfer request is entered in the I/O queue; no 
special action is taken upon completion of the I/O 

Transfers data on the specified channel to a device 
and returns control to the user program only after 
the transfer is complete 



11 



11 



Table 1-5 lists the additional programmed requests that can be used only 
in a foreground/background and extended memory environment. The pro- 
grammed requests followed by (XM) operate only in an extended memory 
environment. 

Table 1-5: Foreground/Background and Extended Memory 
Programmed Requests 



Name 



EMT Code 



Purpose 



.CHCOPY 


375 


13 


•CNTXSW 


375 


33 


.CRAW (XM) 


375 


36 


.CRRG (XM) 


375 


36 


.DEVICE 


375 


14 


.ELAW (XM) 


375 


36 


.ELRG (XM) 


375 


36 



Allows one job to access another job's channel 

Requests that the indicated memory locations be 
part of FB or XM context switch process 

Creates a window in virtual memory 

Creates a region in extended memory 

Allows device interrupts in FB or XM to be disa- 
bled upon program termination 

Eliminates an address window in virtual memory 

Eliminates an allocated region in extended mem- 
ory 



(continued on next page) 
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Table 1-5: Foreground/Background and Extended Memory 
Programmed Requests (Cont.) 



Name 



EMT Code 



Purpose 



•GMCX (XM) 


375 


36 


.MAP (XM) 


375 


36 


.MWAIT 


374 


11 


.PROTECT 


375 


31 


.RCVD 


375 


26 


.RCVDC 






.RCVDW 






.RDBBK (XM) 


— 


— 


.RDBDF (XM) 







.RSUM 



374 



.SDAT 


375 


25 


.SDATC 






.SDATW 






.SPCPS 


375 


41 


.SPND 


374 


1 


.UNMAP (XM) 


375 


36 


.UNPROTECT 


375 


31 


.WDBBK (XM) 


— 


— 


.WDBDF (XM) 









Returns mapping status of a specified window 

Maps a virtual address window to extended mem- 
ory 

Waits for messages to be processed 

Requests that specified vectors in the area from 
to 476 be given exclusively to the current job 

Receives data — allows a job to read messages or 
data sent by another job in an FB environment. 
The three modes correspond to the .READ, 
.READC, and .READW requests 

.Reserves space in a program for a region defini- 
tion block and sets up the region size and region 
status word 

Defines the offsets and bit names associated with 
a region definition block 

Causes the mainline code of the job to be resumed 
after it was suspended by a .SPND request 

Sends messages or data to the other job in an FB 
environment. The three modes correspond to the 
.WRITE, .WRITC, and .WRITW requests 

Used in a completion routine to change the flow of 
control of the mainline code (special feature) 

Causes the running job to be suspended 

Unmaps a virtual address memory window 

Cancels the .PROTECT vector protection request 

Reserves space in a program for a window defini- 
tion block and sets up the associated data 

Defines the offsets and bit names associated with 
a window definition block 



1.2 Using the System Subroutine Library 



The system subroutine library is a collection of FORTRAN-callable 
routines that allow various RT-11 system features to be used by a FOR- 
TRAN programmer. There are no FORTRAN routines in SYSLIB to access 
extended memory under the extended memory (XM) monitor. 

This collection of subroutines is placed in a system library called SYS- 
LIB.OBJ. This library file also contains the overlay handlers, utility func- 
tions, a character string manipulation package, and two-word integer sup- 
port routines. The linker uses this library to resolve undefined globals. It is 
resident on the system device (SY:). 

You should be familiar with the PDP-11 FORTRAN Language Reference 
Manual and the RT-lllRSTSIE FORTRAN IV User's Guide before using 
the material in this chapter. 
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The system subroutine library provides the following capabilities: 

1. Complete RT-11 I/O facilities, including synchronous, asynchronous, 
and event-driven modes of operation. FORTRAN subroutines can be 
activated upon completion of an input/output operation. 

2. Timed scheduling of completion routines. This feature is standard in 
the FB and XM monitors, and is a special feature in the SJ monitor. 

3. Facilities for communication between foreground and background jobs. 

4. FORTRAN language interrupt service routines for user devices. 

5. Complete timer support facilities, including timed suspension of execu- 
tion in a FB or XM environment, conversion of different time formats, 
and time-of-day information. The timer support facilities can use either 
50- or 60-cycle clocks. 

6. All RT-11 auxiliary input/output functions, including the capabilities 
of opening, closing, renaming, and creating or deleting files on any 
device. 

7. All monitor-level information functions, such as job partition parame- 
ters, device statistics, and input/output channel statistics. 

8. Access to the RT-11 command string interpreter (CSI). 

9. A character string manipulation package supporting variable-length 
character strings. 

10. INTEGER*4 support routines that allow two-word integer computa- 
tions. 

NOTE 

When variables are described or mentioned, and unless oth- 
erwise specified, INTEGER means INTEGER*2, (16-bit inte- 
ger) and REAL means REAL*4 (single-precision floating 
point). Integer and real arguments to subprograms are indi- 
cated in this section as follows: 

i = INTEGER*2 arguments 
j = INTEGER*4 arguments 
a = REAL*4 arguments 
d = REAL*8 arguments 

In general, the routines in SYSLIB were written for use with RT-11 V2 or 
later and FORTRAN IV VIB or later versions. The use of SYSLIB with 
prior versions of RT-11 or FORTRAN may lead to unpredictable results. 

1.2.1 System Conventions 

This section describes system conventions that must be followed for proper 
operation of calls to the system subroutine library. Certain restrictions that 
apply are described in Section 1.2.1.7. 
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1.2.1.1 Channel Numbers — A channel number is a logical identifier for a 
file used by FORTRAN. Thus, when you open a file on a particular device, 
you assign a channel number to that file. To refer to an open file, it is only 
necessary to refer to the appropriate channel number. 

The FORTRAN system has 16(decimal) channels available for your use. 
The call IGETC assigns a channel to your program and notifies the FOR- 
TRAN I/O system, which also uses these channels, that the channel is in 
use. When there is no longer need for a channel, the program should close 
the channel with a CLOSEC, ICLOSE or a PURGE SYSLIB call. The chan- 
nel should also be freed and returned to the FORTRAN I/O system with a 
IFREEC call. 

Up to 254(decimal) channels can be activated with the ICDFN call. This 
function sets aside memory in the job area to accommodate status informa- 
tion for the extra channels. Use the ICDFN call during the initialization 
phase of your program. You can use all channels numbered higher than 
15(decimal). The FORTRAN I/O system uses channels through 15(deci- 
mal). 

Channels must be allocated in the main program routine or its subpro- 
grams. Do not allocate channels in routines that are activated as the result 
of I/O completion events or ISCHED or ITIMER calls. 

1.2.1.2 Completion Routines — Completion routines can be written in FOR- 
TRAN or assembly language, depending upon the function called. 

A completion routine is a subprogram that executes asynchronously with a 
main program and is scheduled to run as soon as possible after the comple- 
tion of an associated event, such as an I/O transfer or the passing of a 
specified time interval. All completion routines of the current job have 
higher priority than other parts of the job. Therefore, once a completion 
routine becomes runnable because of its associated event, it interrupts exe- 
cution of the job and continues to execute until it relinquishes control. 

Completion routines are handled differently in the SJ and the FB and XM 
monitors. In the SJ monitor, these routines are totally asynchronous and 
can interrupt one another. Unlike completion routines run under FB and 
XM monitors, which are serialized and run at priority 0, completion 
routines run under an SJ monitor are nested and can interrupt each other. 
In addition, they execute not at priority 0, but at the same priority as the 
device whose interrupt scheduled them. For example, the completion rou- 
tine resulting from a .WRITC programmed request to device TT: runs at 
priority 4. Completion routines from timer requests run at the same prior- 
ity as the system clock. This is particularly important on LSI-11 and 
PDP/03 systems that have only two interrupt levels, ON and OFF, because 
clock interrupts may be lost while lengthy completion routines execute. In 
the FB and XM monitors, completion routines do not interrupt each other 
but are queued and have to wait until the correct job is running. They are 
then scheduled on a first-in flrst-out basis. 

Assembly language completion routines exit with an RTS PC instruction. 
FORTRAN completion routines exit by the execution of a RETURN or END 
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statement in the subroutine. All names of completion routines external to 
the routine being coded that are passed to scheduling calls must be speci- 
fied in an EXTERNAL statement in the FORTRAN program unit issuing 
the call. 

A completion routine written in FORTRAN can have a maximum of two 
arguments as follows: 

Form: SUBROUTINE crtn [(iargl,iarg2)] 

where: 

crtn is the name of the completion routine 

iargl is equivalent to RO on entry to an assembly language com- 
pletion routine 

iarg2 is equivalent to Rl on entry to an assembly language com- 
pletion routine 

If an error occurs in a completion routine or in a subroutine at completion 
level, the error handler traces back through to the original interruption of 
the main program. Thus, the traceback is shown as though the completion 
routine were called from the main program. This lets you know where the 
main program was executing, so that when an error is fatal, it can be 
diagnosed and corrected. 

Certain restrictions apply to completion routines that are activated by the 
following calls: 



INTSET 


ISDATF 


IRCVDC 


ISPFNC 


IRCVDF 


ISPFNF 


IREADC 


ITIMER 


IREADF 


IWRITC 


ISCHED 


IWRITF 


ISDATC 


MRKT 



The restrictions that apply when using these calls are as follows: 

• No channels can be allocated by calls to IGETC or freed by calls to 
IFREEC from a completion routine. Channels to be used by completion 
routines should be allocated and placed in a COMMON block for use by 
the routine. 

• The completion routine cannot perform any call that requires the use of 
the USR, such as LOOKUP and lENTER. See Section 1.2.1.5 for a list of 
the SYSLIB functions that call the USR. 

• Files that are used by the completion routine must be opened and closed 
by the main program. There are, however, no restrictions on the input or 
output operations that can be performed in the completion routine. If 
many files must be made available to the completion routine, they can be 
opened by the main program and saved for later use (without tying up 
RT-11 channels) by an ISAVES call. The completion routine can later 
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make them available by reattaching the file to a channel with an IRE- 
OPN call. 

Even if the completion routine itself does not issue any programmed re- 
quests, but does perform I/O to a logical unit number through the OTS, 
that logical unit number must be opened from the main level. To accom- 
plish this, either the first I/O access or an OPEN statement must be 
issued from main level. A completion routine may not call CLOSE to close 
a logical unit. 

• FORTRAN subroutines are reusable but not reentrant. That is, a given 
subroutine can be used many times as a completion routine or as a rou- 
tine in the main program, but a subroutine executing as main program 
code does not work properly if it is interrupted and then called again at 
the completion level. This restriction applies to all subroutines that can 
be invoked at the completion level while they are active in the main 
program. 

• FORTRAN completion routines can be called only by SYSLIB functions 
that end in F. Conversely, MACRO completion routines cannot be called 
by SYSLIB functions that end in F. Refer to Section 1.1.3.5 for details of 
other restrictions on MACRO completion routines. 



• 



Under the SJ monitor, only one completion function should be active at 
any time. 



1.2.1.3 Device Blocks — A device block is a four-word block of Radix-50 
information that specifies a physical device and a file name. In FORTRAN, 
you can use one of three different methods to set up this block as follows: 

1. You can use the DIMENSION and DATA statements. For example, 

DIHENSIDN IFILE <^) 

DATA IFILE/3RBY t3RFILt3RE »3RXYZ/ 

2. You can translate the available ASCII file description string into Ra- 
dix-50 format, using the SYSLIB calls IRAD50, R50ASC, and RAD50. 
For example, 

REAL*8 FSPEC 

CALL IRAD50 <12,'SY FILE XYZ ' , FSPEC) 

3. You can use the SYSLIB call ICSI to call the Command String Inter- 
preter (CSI) to accept and parse standard RT-11 command strings. 

1 .2.1 .4 INTEGERM Support Functions — This section discusses the initializa- 
tion of INTEGER*4 variables for the FORTRAN programmer. Section 
1.2.6.3 describes the use of INTEGER*4 functions for use by the MACRO 
programmer. 

When the DATA statement is used to initialize INTEGER*4 variables, it 
must specify both the low- and high-order parts. For example, the code 

INTEGER*^ J 
DATA J/3/ 
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Initializes only the first word. The correct way to initialize an INTEGER*4 
variable to a constant such as 3 is as follows: 



INTEGER*4 J 

INTEGER*2 1(2) 

EQUIVALENCE (J»I> 

DATA 1/3,0/ IINITIALI2E J TO 



If you are initializing an INTEGER*4 variable to a negative value such as 
-A, the high-order (second word) part must be the continuation of the two's 
complement of the low-order part. For example, 



INTEGER*^ J 

INTEGER*2 1(2) 

EQUIVALENCE (J»I) 

DATA l/-a,-\/ UNITIALIZE J TO -IX 

The following example is suitable for initializing INTEGER*4 arguments 
to subprograms: 

INTEGER+2 J(2) 

DATA J/3,0/ !LOW ORDER »HIGH ORDER 

1.2.1.5 User Service Routine (USR) Requirements — User- written routines 
that interface to the FORTRAN Object Time System (OTS) must account 
for the location of the RT-11 User Service Routine (USR). The USR occu- 
pies 2K words. When your program calls a SYSLIB routine that requests a 
USR function (such as lENTER or LOOKUP), or when the USR is invoked 
by the FORTRAN OTS, the USR is swapped into memory if it is nonresi- 
dent. The FORTRAN OTS is designed so that the USR can swap over it. 

If you permit the USR to swap over certain kinds of data and code, you will 
obtain unpredictable results. In particular, you should restrict interrupt 
service routines and completion routines to locations outside the USR 
swapping area. To find the limits of this swapping area, examine the link 
map and, if necessary, change the order of object modules and libraries as 
specified to the Linker. 

Subroutines that require the USR are as follows: 

CLOSECICLOSE 

GETSTR (only if first I/O operation on logical unit) 

ICDFN (single job only) 

GTLIN 

ICSI 

IDELET 

IDSTAT 

lENTER 

IFETCH 

IQSET 

IRENAM 

ITLOCK (only if USR is not in use by another job) 

LOCK (only if USR is in a swapping state) 

LOOKUP 

PUTSTR (only if first I/O operation on logical unit) 
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CONTROLLING USR SWAPPING 

You can control USR swapping by using the KMON commands SET USR 
NOSWAP and SET USR SWAP. The SET USR NOSWAP command pre- 
vents swapping and freezes the USR in memory. The command SET USR 
SWAP reverses this, allowing the USR to swap under program control. 

Alternatively, you can compile your FORTRAN main program with the 
/NOSWAP option if you are sure that there is space just below the fore- 
ground partition or RMON to make the USR permanent for the duration of 
your program. Use this option if your program does not need the 2K words 
of memory that the USR occupies. If the /NOSWAP option is not specified, 
the USR swaps over the 2K words of your program above the base 
address — that is, from location lOOO(octal) to llOOO(octal), which is the 
part of a FORTRAN program least likely to violate the USR restrictions. 

To prevent USR swapping for part of the program execution time and allow 
the USR to swap out at other times, use the LOCK, UNLOCK, and 
ITLOCK calls. 

The LOCK call locks the USR into main memory and attaches it to the 
requesting job. The UNLOCK call allows the USR to swap again and to be 
used by another job. The ITLOCK call is used to determine whether an- 
other job is already using the USR. If so, the ITLOCK call returns immedi- 
ately with an error code. This allows the program to try for a lock, but to 
continue with other action if it fails. The LOCK and UNLOCK calls are 
used in a foreground program to prevent interference from the background 
during initialization and completion phases and to minimize the number of 
swaps. 

STRATEGIES IN USR SWAPPING 

If you decide to change the position of code or data to avoid the USR swap- 
ping area, or if you want to move the USR itself, you must consider the 
concept of PSECT (program section) ordering. 

PSECTs contain code and data and are identified by names as segments of 
the object program. The attributes associated with each PSECT direct the 
Linker to combine several separately compiled FORTRAN program units, 
assembly language modules, and library routines into an executable pro- 
gram. 

The order in which program sections are allocated in the executable pro- 
gram is the order that they are presented to the Linker. Applications that 
are sensitive to this ordering typically separate those sections containing 
read-only information (such as executable code and pure data) from impure 
sections containing variables. 

The main program unit of a FORTRAN program (normally the first object 
module in sequence presented to LINK) declares PSECT ordering as shown 
in Table 1-6. 

The USR can swap over pure code, but must not be loaded over constants or 
impure data that can be used as arguments to the USR. The ordering 
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Table 1-6: FORTRAN Program PSECT Ordering 



Section Name 


Attributes 


OTS$I 


RW,I,LCL,REL,CON 


OTS$P 


RW,D,GBL,REL,OVR 


SYS$I 


RW,I,LCL,REL,CON 


USER$I 


RW,I,LCL,REL,CON 


$CODE 


RW,I,LCL,REL,CON 


oTsao 


RW,I,LCL,REL,CON 


SYS$0 


RW,I,LCL,REL,CON 


$DATAP 


RW,D,LCL,REL,CON 


OTS$D 


RW,D,LCL,REL,CON 


OTS$S 


RW,D,LCL,REL,CON 


SYS$S 


RW,D,LCL,REL,CON 


$DATA 


RW,D,LCL,REL,CON 


USER$D 


RW,D,LCL,REL,CON 


.$$$$. 


RW,D,GBL,REL,OVR 


Other COMMON Blocks 


RW,D,GBL,REL,OVR 



shown in Table 1-6 collects all pure sections before impure data in memory. 
The USR can safely swap over sections OTS$I, OTS$P, SYS$I, USER$I, 
and $CODE. When a FORTRAN program is running, the USR will nor- 
mally swap starting at the base of section OTS$I. Location 46 of the System 
Communication Area contains the address where the USR will swap. If 
location 46 is zero, the USR will swap at its default location, below RMON 
and any handlers. 

See the RT-lllRSTSIE FORTRAN IV User's Guide for more information 
on program sections. The RT-11 Software Support Manual also contains 
information on USR swapping and PSECT ordering. 

USR LOCKOUT AND TIMING 

If one job is using the USR and another job requests it, the second job will 
become blocked until the first job releases the USR. The second job may be 
locked out for seconds or minutes at a time. Interrupt service and comple- 
tion routines can run, but not the mainline code. The timing problems that 
arise as a result can be eliminated, or minimized, in one of the following 
four ways: 

1. Do not use devices with slow directory operations, such as cassettes and 
magtapes. 

2. Code real-time operations as completion and interrupt service routines 
in your foreground job so that a locked out mainline program does not 
impact real-time operations. 

3. Separate USR and real-time operations. 

4. Use the ITLOCK call and avoid SYSLIB calls that request the USR 
while the USR is owned by another job. 

Tjrpically, a real-time foreground job can be constructed of (1) an initializa- 
tion phase that opens all required channels and begins a real-time opera- 
tion, (2) a real-time phase that performs interrupt service and I/O opera- 
tions, and (3) a completion phase that halts real-time activity and then 
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closes the channels. Maintaining this structure in the foreground allows 
the background task to do USR operations during the real-time phase with- 
out locking out the foreground. This also simplifies USR swapping since the 
USR can swap over the interrupt routines and I/O buffers as long as they 
are inactive. 

1.2.1.6 Subroutines Requiring Additional Queue Eiements — Certain sub- 
routines require queue elements for their proper operation. These sub- 
routines are as follows: 

IRCVD/IRCVDC/IRCVDF/IRCVDW 

IREAD/IREADC/IREADF/IREADW 

ISCHED 

ISDAT/ISDATC/ISDATF/ISDATW 

ISLEEP 

ISPFN/ISPFNC/ISPFNF/ISPFNW 

ITIMER 

ITWAIT 

lUNTIL 

IWRITC/IWRITE/IWRITF/IWRITW 

MRKT 

MWAIT 

One queue element per job is automatically allocated. Issuing more than 
one request from the list requires extra queue elements. Additional queue 
elements can be allocated through a call to the IQSET function. 

1.2.1.7 System Restriction — The following restrictions must be considered 
when coding a FORTRAN program that uses SYSLIB. 

1. Programs using IPEEK, IPOKE, IPEEKB, IPOKEB, or ISPY to access 
system-specific addresses, such as FORTRAN, monitor, or hardware 
addresses, are not guaranteed to run under future releases or on differ- 
ent configurations. When using these functions, you should document 
their use precisely so that you can check your references against the 
current documentation. Also, these routines may act differently under 
the XM monitor. NOTE: IPEEK and IPOKE are not equivalent to the 
programmed requests .PEEK and .POKE. 

2. Various functions in SYSLIB return values that are of type integer, 
real, and double precision. If you specify an implicit statement that 
changes the defaults for external function types, you must explicitly 
declare the type of those SYSLIB functions that return integer or real 
results. You must also be sure that the arguments to the SYSLIB 
routines are the correct type for the routine. Double-precision functions 
must always be declared to be type DOUBLE PRECISION (or 
REAL*8). Failure to observe this restriction leads to unpredictable re- 
sults. 

3. All names of completion routines external to the routine being coded 
that are passed to scheduling calls (such as ISCHED, ITIMER, and 
IREADC) must be specified in an EXTERNAL statement in the FOR- 
TRAN program issuing the call. 
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4. Certain arguments to SYSLIB calls must be located in such a manner 
as to prohibit the RT-11 User Service Routine (USR) from swapping 
over them at execution time. This kind of swapping can occur when the 
OTS$I section (which contains the all-pure code and data for the mod- 
ule) is less than 2K words in length. Swapping in this uncommon situa- 
tion can be avoided either by typing the SET USR NOSWAP command 
to make the USR resident before starting the job, or by compiling the 
mainline routine with a /NOSWAP option. You can also use the linker 
/BOUNDARY option to make OTS$0 start at word boundary 11000(oc- 
tal). (This problem generally occurs only with small FORTRAN pro- 
grams.) 

In FORTRAN IV, program sections (PSECTs) are used to collect code 
and data into appropriate areas of memory. If the RT-11 USR is needed 
and is not resident, it swaps over a FORTRAN program starting at the 
symbol OTS$I for 2K words of memory. 

5. Certain restrictions apply when using completion or interrupt routines. 
See Section 1.2.1.2 for a description of these restrictions. 

6. Unless explicitly stated, null arguments should not be used in calls to 
SYSLIB routines. 

7. If several arguments to a call are listed as being optional, they must 
either be all present or all omitted. 

1.2.2 Calling SYSLIB Subroutines 

SYSLIB includes both function subprograms and callable subroutines, 
which are called in the same manner as user-written subroutines. 

Function subprograms receive control by means of a function reference as 
follows: 

i = function name ([arguments]) 

The returned function value may be an error code, or it may be information 
that is useful to the calling routine. See the description of the particular 
function for the meaning of the returned function value. 

Call subroutines are invoked by means of a CALL statement as follows: 

CALL subroutine name [(arguments)] 

All subroutines in SYSLIB can be called as FUNCTION programs if a 
return value is desired, or as SUBROUTINE programs if no return value is 
desired. For example, the LOCK subroutine can be referenced as either 

CALL LOCK 

or 

I = LOCKO 

Some subroutines have two acceptable formats. For example, the subrou- 
tine CLOSEC can also be specified as ICLOSE because error codes are 
returned by the subroutine and require an integer return to be useful. 
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Quoted-string literals are useful as arguments of calls to routines in SYS- 
LIB, notably the character string routines. These literals are allowed in 
subroutine and function calls (see Section 1.2.7.3). 



1.2.3 FORTRAN/MACRO Interface 

FORTRAN calling routines and subroutines follow a well-defined set of 
conventions regarding transfer of control, transfer of information, memory 
usage, and register usage. By adhering to these conventions a MACRO 
programmer can write FORTRAN-callable routines such as those in SYS- 
LIB. 

Control is transferred to a subroutine by 

JSR PCtSUBR 

When control passes to the subroutine SUBR, Register 5 (R5) points to an 
argument block that has the format shown in Figure 1-5. 

Figure 1-5: Subroutine Argument Block 

R5=> 



Reserved 



No. of 
arguments 



Address of Argument 1 



Address of Argument 2 



Address of Argument n 



Null arguments in CALL statements must be entered with successive com- 
mas, for example, CALL SUBR (A„B). The value -1 is stored in the argu- 
ment block as the address of a null argument. 

The lower byte of the first word of the argument block contains the number 
of arguments that are passed to the subroutine. The rest of the argument 
block contains the addresses of those arguments. The argument block is 
n + 1 words long for n arguments. 

The program counter is the linkage register. The subroutine obtains its 
arguments through R5. In FORTRAN, the calling program saves the regis- 
ters, and the subroutine leaves the contents of the stack pointer intact 
before returning to the calling program. The RETURN statement of the 
subroutine is replaced by 

RTS PC 
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The name of the subroutine must be declared global with the .GLOBL 
directive in the calling program or with the double colon (::) construction in 
the called program. 

NOTE 

You must make sure that the called program does not modify 
the argument block passed by the calling program to a sub- 
program. 

1.2.3.1 Subroutine Register Usage — A subroutine that is called by a FOR- 
TRAN program does not have to preserve any registers. However, each 
push onto the stack must be matched by a pop off the stack before exiting 
from the routine. 

User-written assembly language programs must preserve any pertinent 
registers before calling FORTRAN subprograms or SYSLIB routines. They 
must then restore registers after the subroutine returns. 

Function subroutines return a single result in a register. Table 1-7 shows 
the register assignments for returning the different variable types. 

Table 1-7: Return Value Conventions for Function Subroutines 



Type 




Result Placed In 


INTEGER*2 


RO 




LOGICAL*! 






INTEGER*4 


RO 


low-order result 


L0GICAL*4 


, Rl 


high-order result 


REAL 


RO 


high-order result (including sign and exponent) 




Rl 


low-order result 


DOUBLE PRECISION 


RO 


highest-order result (including sign and exponent) 




Rl 


next higher order 




R2 


next higher order 




R3 


lowest-order result 


COMPLEX 


RO 


high-order real result 




Rl 


low-order real result 




R2 


high-order imaginary result 




R3 


low-order imaginary result 



Note that floating-point results are returned in the general purpose regis- 
ters and not in the FPU registers. Assembly language subprograms that 
use the FPU Floating Point Unit may be required to save and restore the 
FPU status. 

1.2.3.2 FORTRAN Programs Caiilng IWIACRO Subroutines — FORTRAN pro- 
grams can call MACRO subroutines, but several rules must be followed. 
For example, the following program named INIARR is a MACRO subrou- 
tine that can be called from a FORTRAN program. 
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.TITLE INIARR 








•GLQBL INIARR 






! 


FILENAME INIARR. MAC 






INIARR: 


TST (R5)+ 


5SKIP ARGUMENT COUNT 






MOy (R5)+»RZ 


5PUT ADDRESS OF ARRAY 


INTO R2 




MOV @(R5)+»R1 


?PUT IVAL IN Rl 






MOy @(R5)+»R0 


iAND COUNT INTO RO 






BLE RETURN 


;QUIT if COUNT IS NOT 


POSITIVE 


1$: 


MOV R1.(R2)+ 


5INITIALIZE ARRAY 






DEC RO 


iDECREMENT COUNT 






BNE 1* 


iCONTINUE UNTIL ZERO 




RETURN: 


RTS PC 
.END 







A FORTRAN program calls the preceding routine with 

CALL INIARR (IAR,IVAL,N) 
where: 

INIARR is the name of the subroutine 

lAR is the name of the array to initialize 

IV AL is the value the array is initialized to 

N is the number of elements to initialize 

This program illustrates the rules that must be observed when calling a 
MACRO program. The name of the subroutine is made global by using the 
.GLOBL directive. 

Register 5 (R5) is used to pass the arguments. Thus, in the program 
INIARR, the argument block would appear as shown in Figure 1-6. 

Figure 1-6: Argument Block for Program INIARR 

R5=> 






3 


Address of lAR 


Address of IVAL 


Address of N 



Registers RO through R4 can be freely used since the calling program saves 
them. Once the arguments are retrieved, you can also use R5. 
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On completion, the subroutine returns to the calling program through an 
RTS PC. If your MACRO program pushes data on the stack, you must make 
sure that all data is popped off the stack before the RTS PC is executed. 

The following FORTRAN program named DOFOR calls the subroutine 
INIARR. 

PROGRAM DOFOR 
C 

INTEGER*2 ARRAY 

DIMENSION ARRAY( 10) 

N = 2 

DO 20 IMAL=1 tlO 

CALL INIARR ( ARRAY t lUAL »N ) 

WRITE (5»100) (ARRAY( I) »I=1 >N) 
20 CONTINUE 
100 FORMAT (13) 

STOP 

END 

After you compile and link both programs, run the program by typing 

.RUN DOFOR m 

The initialized array will be output to the terminal as follows: 



1 

2 
2 
3 
3 

a 

5 

5 

6 

6 

7 

7 

8 

8 

9 

9 

10 

10 

STOP 



1.2.3.3 MACRO Routines Calling FORTRAN Programs — If you want to call 
FORTRAN subroutines from a MACRO program, create a dummy main 
program such as 

PROGRAM FORINT 
CALL CALMAC 
STOP 
END 
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where CALMAC is the name of a MACRO program that can call FOR- 
TRAN or MACRO routines. 

Creating a dummy program causes the FORTRAN main program to per- 
form the initialization necessary for FORTRAN subroutines. 

The following MACRO program named CALMAC calls a FORTRAN sub- 
routine named MAXMIN. 





.TITLE CALMAC 




.GLOBL MAXMIN 


CALMAC: 


; 




MOy »ARGBLK »R5 




JSR PCfMAXMIN 




RTS PC 


I : 


.WORD 28. 


J: 


.WORD 7B. 


ARGBLK: 


.WORD 2 




.WORD I 




.WORD J 




.END 



iPOIIMT R5 TO ARGUMENT BLOCK 
iCALL MAXMIN 

JVALUE OF FIRST ARGUMENT 
SMALUE OF SECOND ARGUMENT 
;NUMBER OF ARGUMENTS 

iaddress of first argument 
;address of second argument 



You must set up the argument block either on the stack or in a separate 
area in your MACRO program. You then point R5 to the top of the argu- 
ment block prior to calling the FORTRAN subroutine with a JSR 
PC, MAXMIN. In the above program, the argument block is set up in an 
area of your program. 

The following program named STAKEM performs the same operation as 
the program CALMAC, except that it places the arguments on the stack. 





.TITLE 


STAKEM 




.GLOBL 


MAXMIN, STAKEM 


STAKEM ! 


MOU 


«J.-(SP) 




MOU 


«I »-(SP) 




Moy 


«2,-<SP) 




Moy 


SP .R5 




JSR 


PC. MAXMIN 




add 


#B,SP 




RTS 


PC 


I: 


.WORD 


28. 


J: 


.WORD 
.END 


76. 



If the argument block is set up on the stack, be sure that you remove the 
arguments from the stack prior to the execution of the RTS PC. In general, 
before calling the FORTRAN subroutine, you must save all pertinent regis- 
ters. You do not know which registers the FORTRAN subroutine is using. 
The stack pointer remains unchanged across the call. 

The name of the FORTRAN subroutine that the MACRO program calls 
must be defined as a global. In the FORTRAN subroutine, execute normal 
FORTRAN statements and return to the MACRO program with a RE- 
TURN statement. 
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The following program is the FORTRAN subroutine MAXMIN. 





SUBROUTINE MAKMI N (INI i IN2 ) 






INTEGER BIG. SMALL 






IF (IN1.LT.IN2) GO TO 10 






BIG=IN1 






SMALL=IN2 






TYPE 20. BIG 






TYPE 30. SMALL 






RETURN 




10 


BIG=IN2 
SMALL=IN1 
TYPE 20 .BIG 
TYPE 30. SMALL 




20 


FORMAT ( ' THE BIGGER NUMBER IS ' 


.12) 


30 


FORMAT (' THE SMALLER NUMBER IS 

RETURN 

END 


' .12 



After assembling and linking the programs, using either the program CAL- 
MAC or STAKEM, type 

.RUN FORINT EH 

The program executes as follows: 

THE BIGGER NUMBER IS 7B 
THE SMALLER NUMBER IS 28 
STOP -- 

1.2.4 FORTRAN Programs in a Foreground/Background 
Environment 

FORTRAN programs can be run in a foreground/background environment, 
which permits efficient use of CPU execution time. (See Chapter 15 of 
Introduction to RT—11 for a description of running in an FB environment.) 
The basic steps in running FORTRAN programs that use the FB monitor 
are described in this section. 

Before running your foreground program, you must use the LOAD com- 
mand to load the device handlers required by the foreground job. The device 
handlers are placed in memory between RMON and the USR and KMON, 
which causes USR and KMON to move down in memory. 

Next, you use the FRUN command to load your foreground program in 
memory between the device handlers and the USR, which causes the USR 
and KMON to move further down in memory. It is important that you 
allocate workspace when running a FORTRAN program in the foreground. 
You do this with the /BUFFER:n option of the FRUN command. Also make 
sure that any FORTRAN program you run in the foreground has adequate 
stack space. You can use one of the options supported by the linker (see the 
RT-11 System Utilities Manual). 

The background area must be at least 4K words long to accommodate the 
USR and KMON. Until you run a background job with the RUN command, 
KMON is the background job. 
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When the USR is required, a 2K-word area must be set up in each job for 
the swapping to occur correctly — that is, there must be space for 2K 
words in the background area and 2K words in the foreground area. USR 
swapping is explained in Section 1.2.1.5. 

1.2.4.1 Calculating Workspace for a FORTRAN Foreground Program — Addi- 
tional workspace must be allocated in memory when running a FORTRAN 
program in the foreground of a foreground/background environment. For a 
foreground job, the space is allocated by the /BUFFER:n option of the 
FRUN command. (A background job uses whatever space is available be- 
tween its high limit and the system's low limit.) When you allocate addi- 
tional workspace in memory to run a FORTRAN program in the fore- 
ground, calculate the space required by using the following formula: 

n = [l/2[504 + (35*N) + (R-136) + A*512]] 

where: 

n = number of decimal words 

A = the maximum number of files open at any one time. If double 
buffering is used, A should be multiplied by 2 

N = the maximum number of simultaneously open channels (logical 
unit numbers); the default is 6 

R = maximum formatted record length; the default is 136 charac- 
ters 

This formula must be modified for certain SYSLIB functions. 

The IQSET function requires the formula to include additional space for 
queue elements (qcount) as follows: 

n = [l/2[504 + (35*N) + (R^136) + A*512]] + [10*qcount] 

The ICDFN function requires the formula to include additional space for 
the integer number of channels (num) as follows: 

n = [l/2[504-H(35*N) + (R-136) + A*512]] + [6*num] 

The INTSET function requires the formula to include additional space for 
the number of INTSET calls issued in the program as follows: 

n = [l/2[504 + (35*N) + (Rr-136) + A*512]] + [25*INTSET] 

Any calls, including INTSET, that invoke completion routines must include 
64(decimal) words plus the number of words needed to allocate the second 
record buffer (default is 68[decimal] words). The length of the record buffer 
is controlled by the /RECORD option to the FORTRAN compiler. If the 
/RECORD option is not used, the allocation in the formula must be 136(dec- 
imal) bytes, or the length that was set at FORTRAN installation time. This 
modifies the formula as follows: 

n = [l/2[504 + (35*N) + (R-136) + A*512]] + [64 + R/2] 
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If the /BUFFER option does not allocate enough space in the foreground on 
the initial call to a completion routine, the following message appears: 

?Err Non-FORTRAN error call 

This message also appears if there is not enough free memory for the back- 
ground job or if a completion routine in the single-job monitor is activated 
during another completion routine. In the latter case, the job aborts; you 
should use the FB monitor to run multiple active completion routines. 

1.2.4.2 Running a FORTRAN Program in a Foreground/Background 
Environment — This section briefly describes the procedure for running two 
FORTRAN programs, one in the background and one in the foreground. 

The background program named BACK is as follows: 

PROGRAM BACKGROUND 
IMPLICIT INTEGER(O) 

CALL I POKE ( "aa , "10000. OR, I PEEK ("a4) ) 
100 CALL PRINK 'HELLO FROM THE BACKGROUND') 
ICHAR=ITTINR( ) 
OCHAR=ITTOUR( ICHAR) 
GO TO 100 
END 

This program prints the message "HELLO FROM THE BACKGROUND" 
and will print the message each time you input a character at the terminal. 

The foreground program named FORE is as follows: 

PROGRAM FOREGROUND 
IMPLICIT INTEGER(O) 

CALL I POKE ( "Ua ,"10000.0R.IPEEK("44) ) 
100 CALL PRINT( 'HELLO FROM THE FOREGROUND') 
ICHAR=ITTINR( ) 
OCHAR=ITTOUR( ICHAR) 
GO TO 100 
END 

After compiling both programs, link them. Link the foreground program 
using the LINK command with the /FOREGROUND option. This option 
produces a relocatable load module with a .REL file type. For example, 

.LINK/FOREGROUND FORE (U 

Then you can assign the device that will be used for the output of the 
foreground program. You must also load into memory the peripheral device 
handlers needed by the foreground program. 

The command FRUN loads and starts execution of a .REL program as the 
foreground job. If the command 

•FRUN FORE M) 

is typed at this point, the error message 

?Err G2 FORTRAN start fail 
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will be displayed. This message indicates that additional workspace alloca- 
tion is required and that the /BUFFER option must be used. (Refer to the 
previous section for the formula to calculate the additional space needed.) 
Thus, the command would be typed as follows: 

,FRUN F0RE/BUFFER:7B0 (H) 

Execution of this command results in the following output at the terminal: 

F> 

HELLO FROM THE FOREGROUND 

B> 

I 

The system first identifies the message as foreground output. Then the 
foreground job executes and outputs its message. The background monitor 
next prints the characters B> and a period, indicating that control has 
returned to monitor command mode. Command input remains directed to 
the background job. By typing 

•RUN BACK m 

the message from the background job will be displayed 

HELLO FROM THE BACKGROUND 

Each time a character is input to the terminal, say an "L", the message will 
be repeated. 

LHELLO FROM THE BACKGROUND 

Use the CTRL/F command to direct terminal input to the foreground job. 
The system prints F> to remind you that you are now directing input to the 
foreground job. When you type a character, such as "Y", the foreground job 
message will be displayed. 

F> 

YHELLO FROM THE FOREGROUND 

Type a CTRL/B to return to the background job or a CTRL/C to return to 
monitor command mode. If you are returning to a background environ- 
ment, you should unload the foreground job and any handlers to reclaim 
memory space for background use. 

1.2.5 Linking with FORLIB 

Normally, the default system library file (SYSLIB.OBJ) also includes the 
overlay handlers and the appropriate FORTRAN run-time system routines. 

To add FORLIB.OBJ modules to the default library SYSLIB.OBJ, use the 
following command: 

•LIBRARY/INSERT/REMOyE SYSLIB FORLIB m 
Global? *Di.'RH E) 
Global? EH) 
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1.2.6 SYSLIB Services Not Provided by Programmed Requests 

SYSLIB provides many services that are not provided by programmed re- 
quests. Such services are as follows: 

• Time conversion and date access 

• Program suspension 

• Two-word integer support (INTEGER*4) 

• Radix-50 conversion 

• Character string manipulation 

1.2.6.1 Time Conversion and Date Access — Several calls allow you to per- 
form time conversions and access the system date. 

You use the CVTTIM call to convert a two-word internal format time to 
hours, minutes, seconds, and ticks. The JTIME call converts a time given in 
hours, minutes, seconds, and ticks into the internal two-word time format. 

If you need to print out the time, the TIMASC call converts the time re- 
turned by the .GTIM programmed request into an eight-character ASCII 
string; the TIME call returns the current time of day as an eight-character 
ASCII string. 

The current system date can be accessed by your program with a DATE 
call. The date is returned as a string value. IDATE performs similarly, but 
returns an integer value. DATE and IDATE are part of FORLIB.OBJ. 

1 .2.6.2 Program Suspension — You suspend execution of a running program 
for a specified number of ticks with the ITWAIT call. You use the ISLEEP 
call to suspend a running program for a specified number of hours, minutes, 
seconds, and ticks. The lUNTIL call allows you to suspend job execution 
until a specific time of day, which is given to the routine in hours, minutes, 
seconds, and ticks. You can use this function to periodically collect data and 
to stop processing between acquisitions. 

1.2.6.3 Two-Word Integer Support (iNTEGERM) — You can make calls to SYS- 
LIB to manipulate a 32-bit integer that uses two words of storage. The first 
word contains the low-order part of the value and the second word contains 
the sign and the high-order part of the value. The range of numbers that is 
represented is -2(31) to 2(31)-1. This format differs from the two-word 
internal time format that stores the high-order part of the value in the first 
word and the low-order part in the second word. Table 1-8 shows the calls 
that you can use to convert from one format to another. 

Calls are also available for you to perform arithmetic operations on 
INTEGER*4 values, move a value to a variable, and convert a two-word 
internal time format to and from an INTEGER*4 value. 
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Table 1-8: SYSLIB Conversion Calls 



From To Call 



INTEGER*2 (16-bit integer) INTEGER*4 JICVT 

INTEGER*4 (32-bit integer) INTEGER*2 IJCVT 

INTEGER*4 REAL*4 AJFLT//IAJFLT 

INTEGER*4 REAL*8 DJFLT/IDJFLT 

REAL*4 (2-word floating point) INTEGER*2 JAFIX 

REAL*8 (4-word floating point) INTEGER*4 JDFIX 

1.2.6.4 Radix-50 Conversion — You can convert ASCII characters to or from 
Radix-50. 

IRAD50 converts a specified number of characters of Radix-50 and returns 
the number of characters converted as a function result. RAD50 encodes 
RT-11 file descriptors in Radix-50 notation. R50ASC converts a specified 
number of Radix-50 characters to ASCII. 

1.2.6.5 Character String Operations — SYSLIB provides character string 
functions that perform string operations such as concatenation, compari- 
son, copying, replacing, and computing the number of characters in a 
string. For example, the following program will concatenate two character 
strings. 





.TITLE GETTOO 




•GLOBL CONCAT 




.MCALL .PRINT»,EXIT 


START! 


MOy «ARGBLK tR5 




JSR PCtCONCAT 




.PRINT «STRCON 




.EXIT 


ARGBLK: 


.WORD 3 




.WORD STRNGl 




.WORD STRNGZ 




.WORD STRCON 


STRNGl: 


.ASCIZ /RESEARCH AND/ 


STRNG2! 


.ASCIZ / DEVELOPMENT/ 


STRCON: 


.BLKB 31 




.EMEN 




.END START 



Running this program results in the concatenation of string 1 and string 2, 
and the output at the terminal is 

RESEARCH AND DEVELOPMENT 

The following section describes character string functions in detail. 

1.2.7 Character String Functions 

The SYSLIB character string functions and routines provide variable- 
length string support for RT-11 FORTRAN and for MACRO programs. 
SYSLIB calls perform the following character string operations: 
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Call Operation 

GETSTR Reads character strings from a specified FORTRAN logical 
unit 

PUTSTR Writes character strings to a specified FORTRAN logical unit 

CONCAT Concatenates variable-length strings 

INDEX Returns the position of one string in another 

INSERT Inserts one string into another 

LEN Returns the length of a string 

REPEAT Repeats a character string 

SCOMP Compares two strings 

SCOPY Copies a character string 

STRPAD Pads a string with blanks on the right 

SUBSTR Copies a substring from a string 

TRANSL Performs character modification 

TRIM Removes trailing blanks 

VERIFY Verifies the presence of characters in a string 

Strings are stored in LOGICAL*! arrays that you define and dimension. 
These arrays store strings in ASCII format as one character per array 
element plus a zero element to indicate the current end of the string. 

The length of a string can vary at execution time from zero characters to 
one less than the size of the array that stores the string. The maximum size 
of any string is 32767 characters. Strings can contain any of the seven-bit 
ASCII characters except null(O), since the null character is used to mark 
the end of the string. The inclusion of a terminating zero byte constitutes 
an "ASCIZ" format, which is the format set up by a MACRO assembler 
directive .ASCIZ. This directive automatically sets up strings with a termi- 
nating zero byte. Bit 7 of each character must be cleared. Therefore, the 
valid characters are those whose decimal representations range from 1 to 
127, inclusive. 

The ASCII code used in this string package is the same as that employed by 
FORTRAN for A-type FORMAT items, ENCODE/DECODE strings, and 
object-time format strings. Whenever quoted strings are used as arguments 
in the CALL statement, ASCIZ strings are generated for these routines by 
the FORTRAN compiler. Note that a null string (a string containing no 
characters) can be represented in FORTRAN by a variable or constant of 
any type that contains the value zero, or by a LOGICAL variable or con- 
stant with the .FALSE, value. 

In many routines, it is difficult to predict thfe length of the string produced. 
To prevent a string from overflowing the array that contains it, you can 
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specify an optional integer argument to the subroutine. This argument, 
called len, limits the length of an output string to the value specified for len 
plus one (for the null terminator), so that the array receiving the result 
must be at least len plus one elements in size. 

NOTE 

If the string is larger than the array, other data may be 
destroyed and cause unpredictable results. 

When len is specified, you can also include the optional argument called 
err. Err is a logical variable that should be initialized by the FORTRAN 
program to the .FALSE, value. If a string function is given the arguments 
len and err, and len is actually used to limit the length of the string result, 
then err is set to the .TRUE, value. If len is not used to truncate the string, 
err is unchanged — that is, it retains a .FALSE, value. 

The argument len can appear alone. However, len must appear if err is 
specified. The err argument should be used for GETSTR and PUTSTR. 

Several routines use the concept of character position. Each character in a 
string is assigned a position number. The first character in a string is in 
position one. Each subsequent character has a position number one greater 
than the character that precedes it. 

1.2.7.1 Allocating Character String Variables — A one-dimensional LOGI- 
CAL*! array can contain a single string whose length can vary from zero 
characters to one fewer than the dimensioned length of the array. For ex- 
ample, 

LOGICAL*! A(45) lALLOCATE SPACE FOR STRING VARIABLE A 

allows array A to be used as a string variable that can contain a string of 
44 or fewer characters. Similarly, a two-dimensional LOGICAL*! array 
can be used to contain a one-dimensional array of strings. Each string in 
the array can have a length up to one less than the first dimension of the 
LOGICAL*! array. There can be as many strings as the number specified 
for the second dimension of the LOGICAL*! array. For example, 

LOGICAL*! W(2!,!0) lALLOCATE AN ARRAY OF STRINGS 

creates string array W that has ten string elements, each of which can 
contain up to 20 characters. String I in array W is referenced in subroutine 
or function calls as W(!,I). 

The following example allocates a two-dimensional string array. 

LOGICAL*! T<14.5»7) lALLOCATE A 5 BY 7 ARRAY OF 13-CHARACTER 

ISTRINGS 

Each string in array T may vary in length to a maximum of !3 characters. 
String I,J of the array can be referenced as T(1,I,J). Note that T is the same 
as T(!,!,!). This dimensioning process can create string arrays of up to six 
dimensions (represented by LOGICAL*! arrays of up to seven dimensions). 
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1.2.7.2 Passing Strings to Subprograms — There are three ways to pass 
strings to subprograms. 

1. LOGICAL*! arrays that contain strings can be placed in a COMMON 
block and referenced by any or all routines with a similar common 
declaration. However, when you place a LOGICAL*! array in a com- 
mon block, make sure that the array is even in length, that odd-length 
arrays are paired to result in an overall even length, or that the strings 
are together as the last elements in the COMMON block. Otherwise, all 
succeeding variables in the COMMON block may be assigned odd ad- 
dresses. 

A LOGICAL*! array has an odd length only if the product of its dimen- 
sions is odd. For example, 

LOGICAL*! B(10f7) !(10*7) = 70. EVEN LENGTH 
LOGICAL*! H (21) !Z! IS AN ODD LENGTH 

These might be handled as follows: 

COMMON A! »A2»A3(10) .H(21) ! PLACE ODD-SIZED ARRAY AT END 

or 

COMMON A! ,A2.H(21) ,H!(7) »A3(10) !PAIR ODD-SIZE ARRAYS H AND HI 

These restrictions apply only to LOGICAL*! variables and arrays. 

2. A single string can be passed by using its array name as an argument. 
For example, 

LOGICAL*! A(21) ISTRING VARIABLE A» 20 CHARACTERS MAXIMUM 
CALL SUBR(A) 

passes string A to subroutine SUBR. 

3. If the calling program has declared a multidimensional array, and only 
one string of that array is to be passed to a subroutine, then the subrou- 
tine call should specify the first element of the string to be passed (this 
requires that the first dimension of the array equals the maximum 
length of each string). 

For example, 

LOGICAL*! NAMES (8!. 20) ! 20 NAMES, 80 CHARACTERS EACH 
LOGICAL*! ERR 



DO 10 NAMNUM=! ,20 ! GET ALL 20 NAMES 
10 CALL GETSTR (5 ,NAMES( ! ,NAMNUM) ,80,ERR) IFROMTT 

If the maximum length of a string argument is unknown in a subroutine or 
function, or if the routine is used to handle many different lengths, the 
dummy argument in the routine should be declared as a LOGICAL*! array 
with a dimension of one, such as LOGICAL*! ARG(!). In this case, the 
string routines correctly determine the length of ARG whenever it is used, 
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but it is not possible to determine the maximum size of any string that can 
be stored in ARG. If a multidimensional array of strings is passed to a 
routine, it must be declared in the called program with the same dimen- 
sions that were specified in the calling program. 

NOTE 

The length argument specified in many of the character 
string functions refers to the maximum length of the string 
excluding the necessary null byte terminator. The length of 
the LOGICAL*! array to receive the string must be at least 
one greater than the length argument. 

1.2.7.3 Using Quoted-String Literals — You can use quoted strings as argu- 
ments to any of the string routines that are invoked as functions or with 
the CALL statement. For example, 

CALL SCOHP<NAME t 'SMYTHE » R'jM) 

compares the string in the array NAME to the constant string SMYTHE, R 
and sets the value of the integer variable accordingly. 

1.2.8 System Subroutine Summary 

Table 1-9 lists the SYSLIB subroutines alphabetically within categories, 
the sections in which they are located, and a brief description of each sub- 
routine. Those subroutines prefaced with an asterisk (*) are allowed only in 
a foreground/background environment, under either the FB or XM monitor. 
The SYSLIB subroutines do not support the XM monitor mapping pro- 
grammed requests. Use FORTRAN virtual arrays to access extended 
memory. 

Table 1-9: Summary of SYSLIB Subroutines 



Name Section Description 



File-Oriented Operations 

CLOSEC, 3.3 Closes the specified channel. 

ICLOSE 

IDELET 3.22 Deletes a file from the specified device. 

lENTER 3.25 Creates a new file for output. 

IFPROT 3.27 Changes the file's protection. 

IRENAM 3.46 Changes the name of the indicated file. 

ISFDAT 3.53 Changes the file's creation date. 

LOOKUP 3.V9 Opens an existing file for input and/or output via the speci- 

fied channel. 



(continued on next page) 
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Table 1-9: Summary of SYSLIB Subroutines (Cont.) 



Name 



Section 



Description 



Data Transfer Operations 



lABTIO 


3.12 


GTLIN 


3.11 


*IRCVD 


3.44 


*IRCVDC 




*IRCVDF 




*IRCVDW 





IREAD 



IREADC 



IREADF 



IWAIT 



IWRITC 



IWRITE 



IWRITF 



IWRITW 



3.45 



3.45 



3.45 



IREADW 


3.45 


*ISDAT 


3.51 


*ISDATC 




*ISDATF 




*ISDATW 




ITTINR 


3.59 


ITTOUR 


3.60 



3.64 



3.65 



3.65 



3.65 



3.65 



Aborts I/O operations on a specified channel. 

Transfers a line of input from the console terminal or indi- 
rect file (if active) to the user program. 

Receives data. Allows a job to read messages or data sent by 
another job In an FB environment. The four modes corre- 
spond to the IREAD, IREADC, IREADF, and IREADW 
modes. 

Transfers data from a file to a memory buffer and returns 
control to the user program when the request is entered in 
the I/O queue. No special action is taken upon completion of 
I/O. 

Transfers data from a file to a memory buffer and returns 
control to the user program when the request is entered in 
the I/O queue. Upon completion of the read, control transfers 
to the assembly language routine specified in the IREADC 
function call. 

Transfers data from a file to a memory buffer and returns 
control to the user program when the request is entered in 
the I/O queue. Upon completion of the read, control transfers 
to the FORTRAN subroutine specified in the IREADF func- 
tion call. 

Transfers data from a file to a memory buffer and returns 
control to the program only after the transfer is complete. 

Allows the user to send messages or data to the other job in 
an FB environment. The four functions correspond to the 
IWRITE, IWRITC, IWRITF, and IWRITW modes. 

Gets one character from the console keyboard. 

Transfers one character to the console terminal. 

Waits for completion of all I/O on a specified channel (com- 
monly used with the IREAD and IWRITE functions). 

Transfers data to a file and returns control to the user pro- 
gram when the request is entered in the I/O queue. Upon 
completion of the write, control transfers to the assembly 
language routine specified in the IWRITC function call. 

Transfers data to a file and returns control to the user pro- 
gram when the request is entered in the I/O queue. No spe- 
cial action is taken upon completion of the I/O. 

Transfers data to a file and returns control to the user pro- 
gram when the request is entered in the I/O queue. Upon 
completion of the write, control transfers to the FORTRAN 
subroutine specified in the IWRITF function call. 

Transfers data to a file and returns control to the user pro- 
gram only after the transfer is complete. 



FB and XM monitors only. 
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Table 1-9: Summary of SYSLIB Subroutines (Cont.) 



Name 



Section 



Description 



tMTATCH 


3.81 


tMTDTCH 


3.82 


tMTGET 


3.83 


tMTIN 


3.84 


tMTOUT 


3.85 


tMTPRNT 


3.86 


tMTRCTO 


3.87 


tMTSET 


3.88 


tMTSTAT 


3.89 


*MWAIT 


3.90 


PRINT 


3.91 



Attaches a particular terminal in a multiterminal environ- 
ment. 

Detaches a particular terminal in a multiterminal environ- 
ment. 

Provides information about a particular terminal in a multi- 
terminal system. 

Transfers characters from a specific terminal to the user pro- 
gram in a multiterminal system. 

Transfers characters to a specific terminal in a multitermi- 
nal system. 

Prints a message to a specific terminal in a multiterminal 
system. 

Enables output to terminal by canceling the effect of a previ- 
ously typed CTRL/O. 

Sets terminal and line characteristics in a multiterminal 
system. 

Returns multiterminal system status. 

Waits for messages to be processed. 

Outputs an ASCII string to the console terminal. 



Channel-Oriented Operations 

ICDFN 3.16 Defines additional I/O channels. 

Allows access to files currently open in another job's envi- 
ronment. 

Returns the status of a specified channel. 

Returns the specified RT-11 channel to the available pool of 
channels for the FORTRAN I/O system. 

Allocates an RT-11 channel and informs the FORTRAN I/O 
system of its use. 

Returns the RT-11 channel number with which a FOR- 
TRAN logical unit is associated. 

Restores the parameters stored via an ISAVES function and 
reopens the channel for I/O. 

Stores five words of channel status information into a user- 
specified array and deactivates the channel. 

Deactivates a channel. 



*ICHCPY 


3.17 


ICSTAT 


3.21 


IFREEC 


3.28 


IGETC 


3.29 


ILUN 


3.33 


IREOPN 


3.47 


ISAVES 


3.48 


PURGE 


3.92 



Device and File Specifications 

lASIGN 3.15 Sets information in the FORTRAN logical unit table. 

ICSI 3.20 Calls the RT-11 CSI in special mode to decode file specifica- 

tions and options. 



^ With multiterminal support only. 
* FB and XM monitors only. 
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Table 1-9: Summary of SYSLIB Subroutines (Cont.) 



Name 



Section 



Description 



Timer Support 

CVTTIM 

GTIM 
ICMKT 



ISCHED 

ISDTTM 
HSLEEP 

ITIMER 

HTWAIT 
tlUNTIL 

JTIME 
MRKT 

SECNDS 
TIMASC 
TIME 



Operations 

3.5 Converts a two-word Ikternal format time to hours, minutes, 

seconds, and ticks. 



3.9 
3.19 

3.49 

3.52 
3.54 

3.57 

3.61 
3.62 

3.76 
3.80 

3.103 
3.108 
3.109 



RT-11 Services 

CHAIN 3.2 

*DEVICE 3.6 



GTJBJGTJB 
IDSTAT 



3.10 
3.24 



Gets time of day. 

Cancels an unexpired ISCHED, ITIMER, or MRKT request 
(valid under FB and XM, and for SJ monitors with timer 
support, a SYSGEN option). 

Schedules the specified FORTRAN subroutine to be entered 
at the specified time of day as an asynchronous completion 
routine (valid under FB and XM, and for SJ monitors with 
timer support, a special feature). 

Changes the system date and time. 

Suspends main program execution of the running job for a 
specified amount of time; completion routines continue to 
run. 

Schedules the specified FORTRAN subroutine to be entered 
as an asynchronous completion routine when the time inter- 
val specified has elapsed (valid under FB and XM, and for 
SJ monitors with timer support, a special feature). 

Suspends the running job for a specified amount of time; 
completion routines continue to run. 

Suspends the main program execution of the running job 
until a specified time of day; completion routines continue to 
run. 

Converts hours, minutes, seconds, and ticks into two-word 
internal format time. 

Schedules an assembly language routine to be activated as 
an asynchronous completion routine after a specified inter- 
val (valid under FB and XM, and for SJ monitors with timer 
support, a special feature). 

Returns the current system time in seconds past midnight 
minus the value of a specified argument. 

Converts a specified two-word internal format time into an 
eight-character ASCII string. 

Returns the current system time of day as an eight-charac- 
ter ASCII string. 



* SYSGEN option in SJ monitor. 
FB and XM monitors only. 



Chains to another program (from the background job only). 

Specifies actions to be taken on normal or abnormal pro- 
gram termination, such as turning off interrupt enable on 
user-programmed devices. 

Returns the parameters of the specified job. 
Returns the status of the speciflfied device. 
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Table 1-9: Summary of SYSLIB Subroutines (Cont.) 



Name 



Section 



Description 



IFETCH 


3.26 


IQSET 


3.42 


ISPFN 


3.55 


ISPFCN 




ISPFNF 




ISPFNW 




*ITLOCK 


3.58 


LOCK 


3.78 



Loads a device handler into memory. 

Expands the size of the RT-11 monitor queue from the free 
space managed by the FORTRAN system. 

Issues special function requests to various handlers, such as 
magtape. The four modes coiTespond to the IWRITE, 
IWRITC, IWRITF, and IWRITW modes. 



Indicates whether the USR is currently in use by another job 
and performs a LOCK if the USR is available. 

Makes the RT-11 monitor User Service Routine (USR) per- 
manently resident until an UNLOCK function is executed. 
If necessary, a portion of the user's program is swapped out 
to make room for the USR. 

Allows a program to access variables passed across a chain. 

Enables output to the terminal by canceling the effect of a 
previously typed CTRL/O. 

Causes the main program execution of a job to resume at the 
point it was suspended by a SUSPND function call. 

Intercepts a CTRL/C command initiated at the console ter- 
minal. 

Passes command lines to the keyboard monitor for execution 
after the program exits. 

Suspends main program execution of the running job; com- 
pletion routines continue to execute. 

Releases the USR if a LOCK was performed; the user pro- 
gram is swapped in if required. 



RCHAIN 


3.96 


RCTRLO 


3.97 


*RESUME 


3.99 


SCCA 


3.100 


SETCMD 


3.104 


*SUSPND 


3.107 


UNLOCK 


3.112 



INTEGER*4 Support Functions 



AJFLT 


3.1 


DJFLT 


3.7 


lAJFLT 


3.14 


IDJFLT 


3.23 


IJCVT 


3.32 


JADD 


3.66 


JAFIX 


3.67 


JCMP 


3.68 



JDFIX 



3.69 



Converts a specified INTEGER*4 value to REAL*4 and re- 
turns the result as the function value. 

Converts a specified INTEGER*4 value to REAL*8 and re- 
turns the result as the function value. 

Converts a specified INTEGER*4 value to REAL*4 and 
stores the result. 

Converts a specified INTEGER*4 value to REAL*8 and 
stores the result. 

Converts a specified INTEGER*4 value to INTEGER*2. 

Computes the sum of two INTEGER*4 values. 

Converts a REAL*4 value to INTEGER*4. 

Compares two INTEGER*4 values and returns an 
INTEGER*2 value that reflects the signed comparison re- 
sult. 

Converts a REAL*8 value to INTEGER*4. 



FB and XM monitors only. 
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Table 1-9: Summary of SYSLIB Subroutines (Cont.) 



Name 



Section 



Description 



JDIV 

JICVT 
JJCVT 

JMOV 
JMUL 
JSUB 



3.70 

3.71 
3.72 

3.73 
3.74 
3.75 



Computes the quotient and remainder of two 
INTEGER*4 values. 

Converts an INTEGER*2 value to INTEGER*4. 

Converts the two-word internal time format to 
INTEGER*4 format, and vice versa. 

Assigns an INTEGER*4 value to a variable. 

Computes the product of two INTEGER*4 values. 

Computes the difference between two INTEGER*4 
values. 



Character String Functions 

CONCAT 3.4 

GETSTR 3.8 



INDEX 



3.34 



INSERT 


3.35 


ISCOMP 


3.50 


IVERIF 


3.63 


LEN 


3.77 


PUTSTR 


3.93 


REPEAT 


3.98 


SCOMP 


3.101 


SCOPY 


3.102 


STRPAD 


3.105 


SUBSTR 


3.106 


TRANSL 


3.110 


TRIM 


3.111 


VERIFY 


3.113 



Concatenates two variable-length strings. 

Reads a character string from a specified FORTRAN logical 
unit. 

Returns the location in one string of the first occurrence of 
another string 

Replaces a portion of one string with another string. 

Compares two character strings. 

Indicates whether characters in one string appear in an- 
other. 

Returns the number of characters in a specified string. 

Writes a variable-length character string on a specified 
FORTRAN logical unit. 

Concatenates a specified string with itself to provide an indi- 
cated number of copies and stores the resultant string. 

Compares two character strings. 

Copies a character string from one array to another. 

Pads a variable-length string on the right with blanks to 
create a new string of a specified length. 

Copies a substring from a specified string. 

Replaces one string with another after performing character 
modification. 

Removes trailing blanks from a character string. 

Indicates whether characters in one string appear in an- 
other. 
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Table 1-9: Summary of SYSLIB Subroutines (Cont.) 



Name 



Section 



Description 



Radix-50 Conversion Operations 

IRAD50 3.43 Converts characters in ASCII format to Radix-50, 

returning the number of characters converted. 

Converts characters in Radix-50 format to ASCII. 

Converts six ASCII characters, returning a REAL*4 
result that is the two-word Radix-50 value. 



R50ASC 


3.94 


RAD50 


3.95 


Miscellaneous Services 


lADDR 


3.13 


IGETSP 


3.30 


INTSET 


3.36 


IPEEK 


3.37 


IPEEKB 


3.38 


IPOKE 


3.39 


IPOKEB 


3.40 


IPUT 


3.41 



ISPY 



3.56 



Obtains the memory address of a specified entity. 

Returns the address and size (in words) of free space ob- 
tained from the FORTRAN system. 

Establishes a specified FORTRAN subroutine as an inter- 
rupt service routine with a specified priority. 

Returns the value of a word located at a specified absolute 
memory address. 

Returns the value of a byte located at a specified byte ad- 
dress. 

Stores an integer value in an absolute memory location. 

Stores an integer value in a specified byte location. 

Changes the value of the word located at an offset specified 
from the beginning of the RT-11 monitor. 

Returns the integer value of the word located at a specified 
offset from the beginning of the RT-11 resident monitor. 
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Chapter 2 

Programmed Request Description and Examples 



This chapter presents the programmed requests alphabetically, describing 
each one in detail and providing an example of its use in a program. Also 
described are macros and subroutines that are used to implement device 
handlers and interrupt service routines. The following parameters are com- 
monly used as arguments in the various calls: 

addr an address, the meaning of which depends on the request 

being used. 

area a pointer to the EMT argument block for those requests 

that require a block. 

blk a block number specifying the relative block in a file or 

device where an I/O transfer is to begin. 

buf a buffer address specifying a memory location into which 

or from which an I/O transfer will be performed; this ad- 
dress has to be word-aligned — that is, located at an even 
address and not a byte or odd address. 

cblk the address of the five-word block where channel status 

information is stored. 

chan a channel number in the range 0-376(octal). 

chrcnt a character count in the range l-255(decimal). 

code a flag used to indicate whether the code is to be set in an 

EMT 375 programmed request. 

crtn the entry point of a completion routine. 

dblk a four-word Radix-50 descriptor block that specifies the 

physical device, file name, and file type to be operated 
upon (see Section 1.1.2.6). 

func a numerical code indicating the function to be performed. 

jobblk a pointer to a three-word ASCII system job name. 

jobdev a pointer to a four-word system-job descriptor where the 
first word is a Radix-50 device name and the next three 
words contain an ASCII system-job name (for keyword ar- 
gument use, refer to this as a "dblk"). 

num a number, the value of which depends on the request. 
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seqnum a file number. 

For cassette operation, a value of is assumed if this argu- 
ment is blank. 

For magtape operation, this argument describes a file se- 
quence number. The values that the argument can have 
are described under the applicable programmed requests. 

unit the logical unit number of a particular terminal in a mul- 

titerminal system. 

went a word count specifying the number of words to be trans- 

ferred to or from the buffer during an I/O operation. 

Many programmed requests are qualified as special features. These re- 
quests are enabled only if you performed a system generation process, that 
is, they are not available in a distributed monitor. 



2.1 .ABTIO 



The .ABTIO programmed request allows a running job to stop all outstand- 
ing I/O operations on a channel without terminating the program. 

When .ABTIO is issued, the handler for the device opened on the specified 
channel is entered at its abort entry point. After the handler abort code is 
executed, control returns to the user program. 

This request cannot be issued from a completion routine. 

Macro Call: .ABTIO chan 

where: 

chan is the channel number for which to abort I/O 
Request Format: 
RO = 
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chan 



Errors: 

none 
Example: 

.TITLE ABTIO. MAC 

iThis is an example of the iABTIO request. The .ABTIO request 
lis useful for immediately terminating .READC/ . WRITC or 4READ/ 
i. WRITE I/O on a particular channel without issuing a .EXIT or 
i.HRESETi which would terminate the pro<tram or stop I/O on all 
f channe 1 s * 

.MCALL .ABTIO, .ENTER, . SCCA 



TART: 


.SCCA 


• AREAittCTCWRD 




.ENTER 


• AREA,»1 ,«FILNAM 


OLOOPs 


, 





ilnhibit CTRL/C 

iOpen channel 1 as output file 

iPerform I/O to the file... 
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TST 


CTCWRD 






BPL 


IDLOOP 






.ABTID 

♦ 


«1 




AREA: 


.BLKU 


a 




CTCWRD: 


.MORD 
.END 





2.2 


.CDFN 







!Has CTRL/C been typed? 
iNo I continue file I/O 
lYes) stop I/O on channel 1 

iContinue other prooessini 



iEliT ar!lument block 
iTepminal status word 



The .CDFN request redefines the number of I/O channels. Each job, 
whether foreground or background, is initially provided with 16(decimal) 
I/O channels numbered 0-15. .CDFN allows the number to be expanded to 
as many as 255(decimal) channels (0-254 decimal, or 0-376 octal). Channel 
377 is reserved for use by the monitor. 

The space for the new channels is taken from within the user program. 
Each I/O channel requires five words of memory. Therefore, you must allo- 
cate 5*n words of memory, where n is the number of channels to be defined. 

It is recommended that you use the .CDFN request at the beginning of a 
program before any I/O operations have been initiated. If more than one 
.CDFN request is used, the channel areas must either start at the same 
location or not overlap at all. The two requests .SRESET and .HRESET 
cause the channels to revert to the original 16 channels defined at program 
initiation. Hence, you must reissue any .CDFNs after using .SRESET or 
.HRESET. The keyboard monitor command CLOSE does not work if your 
program defines new channels with the .CDFN request. 

The .CDFN request defines new channels so that the space for the previ- 
ously defined channels cannot be used. Thus, a .CDFN for 20(decimal) 
channels (while 16 original channels are defined) creates 20 new I/O chan- 
nels; the space for the original 16 is unused, but the contents of the old 
channel set are copied to the new channel set. 

If a program is overlaid, the overlay handler uses channel 17(octal) and this 
channel should not be modified. (Other channels can be defined and used as 
usual.) 

If an XM monitor environment, the area supplied for additional channels 
specified by the .CDFN request must lie in the lower 28K words of memory. 
In addition, it must not be in the virtual address space mapped by Kernel 
PARI, specifically the area from 20000 to 37776(octal). If you supply an 
invalid area, the system generates an error message. 

Macro Call: .CDFN area,addr,num 



where: 



area is the address of a three-word EMT argument block 
addr is the address where the I/O channels begin 
num is the number of I/O channels to be created 
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Request Format: 
RO —* area: 



Errors: 



Example: 



15 





addr 


num 



Code Explanation 

An attempt was made to define fewer than or the same num- 

ber of channels that already exist. In an XM environment, 
an attempt to violate the PARI restriction sets the carry bit 
and returns error code in byte 52. 



.TITLE CDFN.MflC 

i + 

i .CDFN - This is an example in the use of the .CDFN request. The 
i example defines 32 neu channels to reside in the body of the 
> pro 9ra«. 





.MCALL 


.CDFN. .PRINT 


.EXIT 




START: 


.CDFN 


«AREA>«CHANL 


»32, 


iUse .CDFN to define 32. new channels 




5CC 


1$ 




iBranoh if successful 




.PRINT 


•BADCO 




iPrint failure messase on console 




.EXIT 






iExit prosram 


1»: 


.PRINT 
.EXIT 


•GDODCD 




iPrint success wessase 
iThen exit 


AREA! 


.BLKW 


3 




iEMT Arsument BlocK 


CHANL: 


.BLKM 


5»32. 




iSpace for new channels 


BADCDs 


.ASCIZ 


/? .CDFN Fail 


ed ?/ 


iFailure messase 


GDODCD: 


.ASCIZ 


/.CDFN Successful/ 


iSuccess wessase 



.END 



START 



2.3 .CHAIN 



The .CHAIN request allows a background program to pass control directly 
to another background program without operator intervention. Since this 
process can be repeated, a long "chain" of programs can be strung together. 

The area in low memory from locations 500-507 contains the device name 
and file name (in Radix-50) to be chained to. The area from locations 
510-777 is used to pass information between the chained programs. 

Macro Call: .CHAIN 

Request Format: 

RO = 

Notes: 

1. Make no assumptions about which areas of memory remain intact 
across a .CHAIN. In general, only the resident monitor and locations 
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500-777 are preserved across a .CHAIN. In a .CHAIN to or from a 
virtual job, locations 500-777 are not preserved. 

2. I/O channels are left open across a .CHAIN for use by the new program. 
However, new I/O channels opened with a .CDFN request are not avail- 
able in this way. Since the monitor reverts to the original 16 channels 
during a .CHAIN, programs that leave files open across a .CHAIN 
should not use .CDFN. Furthermore, nonresident device handlers are 
released during a .CHAIN request and must be fetched again by the 
new program. Note that FORTRAN logical units do not stay open 
across a .CHAIN. 

3. An executing program determines whether it was chained to or RUN 
from the keyboard by examining bit 8 of the Job Status Word. The 
monitor sets this bit if the program was invoked with .CHAIN request. 
If the program was invoked with R or RUN command, this bit remains 
cleared. If bit 8 is set, the information in locations 500-777 is preserved 
from the program that issued the .CHAIN and is available for the cur- 
rently executing program to use. Again, locations 500-777 are not pre- 
served in a .CHAIN to or from a virtual job. 

An example of a calling and a called program is MACRO and CREF. 
MACRO places information in the chain area, locations 500-777, then 
chains to CREF. CREF tests bit 8 of the JSW. If it is clear, it means 
that CREF was invoked with the R or RUN command and the chain 
area does not contain useful information. CREF aborts itself immedi- 
ately. If bit 8 is set, it means that CREF was invoked with .CHAIN and 
the chain area contains information placed there by MACRO. In this 
case, CREF executes properly. 



Errors: 



.CHAIN is implemented by simulating the monitor RUN command 
and can produce any errors that RUN can produce. If an error occurs, 
the .CHAIN is abandoned and the keyboard monitor is entered. 

When using .CHAIN, be careful with initial stack placement. The 
linker normally defaults the initial stack to lOOO(octal); if caution is 
not observed, the stack can destroy chain data before it can be used. 



Example: 



.TITLE CHAIN. MAC 

.CHAIN - This BKaniple demonstrates the use of the .CHAIN 
prosram re^iuest. It chains to prasram 'CTEST.SAy and passes it 
a command line typed in at the console terminal. As an exercise 
write the proSram 'CTEST' - in itt oheoK to see if it was chained 
to I and if so. echo the data passed to iti otherwise print the 
messase "Was not chained to". 



iRl => Chain area 

iR2 => RAD50 ProSram Filespec 

iMoue the ProSram Filespec 

iinto the Chain area... 

I 

iAsK for the data to be passed 





.MCALL 


. CHAIN. .TT 


START! 


Moy 


•500.R1 




MO'.' 


•CHPTR.R2 




.REPT 


a 




MOV 


(R2)+.(R1) 




.ENDR 






.PRINT 


•PROMT 
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LOOP! 



CHPTR: 



PROMT: 



.TTYIN 

MOWB 

CMPB 

BNE 

CLRB 

.CHAIN 

.RAD50 

.RAD50 

.RAD50 

.ASCII 

.END 



R0.(R1)+ 
RO .sl2 
LOOP 
SRI 



!Now Set a "command" line 

ito pass to the chained program 

iin locations 510 and lip. 

iLoop until line feed. 

!Put in a null byte as a terminator. 

!Chain to the next ppotfram. 

;RAD50 Fi le spec , . . 



/DK/ 

/CTEST / 

/SAW/ 

/Enter data to be passed to CTEST > /<200> 

START 



• IN CASE YOU DON'T HAUE TIME HERE'S AN EXAMPLE » 
» 'CTEST. MAC PROGRAM... « 





.TITLE 


CTEST. MAC 












.MCALL 


.PRINT. .EXIT 












JSW = ai\ 










iLocation of JSW 




CHAIN* = 


aoo 








;CHAIN bit in JSW 


CTEST: 


BIT 

BEO 

.PRINT 

MOM 

.PRINT 

.EXIT 


•CHAIN*. esJSW 

1* 

•CHAIND 

•510.ro 








iWere we chained to? 

JBranch if not 

iSay ue were... 

iGet addr of start of data 

iPrint it out 

iEx i t p roaram 


1$: 


.PRINT 
.EXIT 


•NOCHN 








iSay we weren't chained to 
iThen exit 


CHAIND; 


.ASCIZ 


/CTEST was chain 


ed 


to 


- and here's the data passed 


NOCHN: 


.ASCIZ 


/CTEST uas not 


c 


hained 


to/ 




.END 


CTEST 











2.4 .CHCOPY (FB and XM Only) 

The .CHCOPY request opens a channel for input, logically connecting it to 
a file that is currently open by another job for either input or output. This 
request can be used by a foreground, background, or system job and must 
be issued before the first .READ or .WRITE request on that channel. 

.CHCOPY is valid only on files on disk (including diskette) or DECtape. 
However, no errors are detected by the system if another device is used. (To 
close a channel following use of .CHCOPY, use either the .CLOSE or 
.PURGE request.) 

Macro Call: .CHCOPY area,chan,ochan [,jobblk] 
where: 



area 
chan 
ochan 
jobblk 



is the address of a three-word EMT argument block 

is the channel the current job will use to read the data 

is the channel number of the other job's channel to be copied 

is a pointer to a three-word ASCII logical job name that 
represents a system job (see the RT-11 System Utilities 
Manual) 
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Request Format: 
RO -^ area: 
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chan 



ochan 



jobblk 



Notes: 

1. If the other job's channel was opened with .ENTER in order to create a 
file, the copier's channel indicates a file that extends to the highest 
block that the creator of the file had written at the time the .CHCOPY 
was executed. 

2. A channel open on a non-file-structured device should not be copied, 
because intermixture of buffer requests can result. 

3. A program can write to a file (that is being created by the other job) on 
a copied channel just as it could if it were the creator. When the copier's 
channel is closed, however, no directory update takes place. 

4. Foreground and background jobs may optionally leave the jobblk argu- 
ment blank or set it to zero. This causes the job name to default to F if 
the background job issued the request, or to B if the foreground job 
issued the request. 



Errors: 



Code 





Example: 



Explanation 

Other job does not exist, does not have enough channels de- 
fined, or does not have the specified channel (ochan) open. 

Channel (chan) already open. 



i + 



.CHCOPY - This is an eKawPle in the use of the .CHCOPY request. 
The example consists of two pro^ramsi a Foreground Job uhich 
creates a file and sends a message to a BacK<rround program 
uhioh copies the FG channel and reads a record froifi the file. 
Both pro9rairts must be assembled and linked separately. 

.TITLE CHCOPF.MAC 

i This is the Foreground prosram ... 
i - 

.MCflLL .ENTER..PRINT..SDATW..EXIT..RCUDW..CLOSE..WRITW 

•AREfttRS iR5 => EMT arSument block 

R5 i»0 .«FILE «»5 iCreate a 5 block file 

R5 i»0 tsRECRD itt25B . t<»a iWrite a record BG is interested in 

ENTERR iBranoh on error 

R5i«BUFRi»2 iSend messaSe with info to BG 

. ;Do some other processin<r 

R5.«BUFR(«l iWhen it's time to exiti make sure 

»0 IBG is done with the file 

sFEXIT iTell user we're exiting 

iEx it the p rosr ram 
ttERMSG iPrint error message 

ithen exit 



STARTF: 


MOV 




.ENTER 




.WRITW 




BCS 




.SDATW 




.RCUDW 




.CLOSE 




.PRINT 




.EXIT 


ENTERR! 


.PRINT 




.EXIT 
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FILE: 


.RAD50 


/DK OUFILE/ 


iFile spec for .ENT 




.RAD50 


/TMP/ 






AREA: 


.BLKkl 


5 




iEMT argument blacK 


BUFR; 


.MORD 







SChannel « 




.MORD 


a 




iBIooK « 


RECRD; 


.BLKW 


25S. 




fFile record 


ERMBG: 


.ASCIZ 


/?Enter 


Error?/ 


iError messa^le text 


FEXIT: 


.ASCIZ 
.END 


/FG Job 
STARTF 


exiting/ 


iExit messase 



i + 



.TITLE CHCOPB.MAC 

I This is the BacKaround prosraw ... 
! - 

.MCALL .CHCDPY,.RCyDW,.READW >. EXIT .. PRINT .. SDATk 



STARTS! 


Moy 


«AREA.R5 i 




.RCVDW 


RS.KMSG.wZ i 




BCS 


1* i 




.CHCOPY 


R5,ttO,MSG + 2 ! 




BCS 


2$ i 




.READU 


R5 .»0 iSBUFF i«25B. iMSG + fl 




BCS 


3t i 




1 

.SDATW 


R5,*MSG,«1 i 




.PRINT 


SBEXIT ! 




.EXIT 


; 


1$: 


Moy 


• NOJOB iRO ; 




BR 


at ; 


2»; 


MOV 


»NOCH>RO ; 




BR 


4* ; 


3«; 


Moy 


•RDERR.ro ! 


at: 


.PRINT 
.EXIT 


i 


AREA: 


.BLKW 


5 i 


MSG: 


.BLKW 


3 i 


BUFF; 


.BLKW 


256. ; 


BEXIT: 


.ASCIZ 


/Channel-Record copy su 


NOJOB: 


.ASCIZ 


/?No FG Job?/ ! 


NOCH; 


.ASCIZ 


/?FG channel not open?/ 


RDERR: 


.ASCIZ 


/?Read Error?/ 




.END 


STARTS 



R5 => EMT ar9 block 

Wait for messaSe from FG 

Branch if no FG 

Channel » is 1st word of messase 

Branch if FG channel not open 

I iRead blooK which is 2nd word o1 

B ranch if read error 

Continue processing... 

Tell FG we're thru with file 

Tell user we ' re thru 

then exit prosram 

RO => No FG e rro r mss 

Branch to print ms9 

RO => FG oh not open msS 

5 ranch . . . 

RO -> Read err msa 

Print proper error msai 

then exit. 

EMT argument blK 

MessaSe buffer 

File buffer 

locessful/ 

Error messaae s < . > 



2.5 .CLOSE 



The .CLOSE request terminates activity on the specified channel and frees 
it for use in another operation. The handler for the associated device must 
be in memory if the file was created with a .ENTER programmed request. 

Macro Call: .CLOSE chan 

Request Format: 

RO = 



chan 



A .CLOSE request specifying a channel that is not open is ignored. 

A file opened with .LOOKUP does not require any directory operations 
when a .CLOSE is issued, and the USR does not have to be in memory for 
such a .CLOSE. The USR is required if, while the channel is open, a request 
was issued that required directory operations. The USR is always required 
for special structured devices such as magtape. 

A .CLOSE is required on any channel opened with .ENTER if the associ- 
ated file is to become permanent. 
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NOTE 

Do not close channel 17(octal) if your program is overlaid, 
because overlays are read on that channel. 

A .CLOSE performed on a file opened with .ENTER causes the device direc- 
tory to be updated to make that file permanent. The first permanent file in 
the directory with the same name, if one exists, is deleted, provided that it 
is not protected. When a file that is opened with an .ENTER request is 
closed, its permanent length reflects the highest block written since it was 
entered. For example, if the highest block written is block number 0, the 
file is given a length of 1; if the file was never written, it is given a length 
of 0. If this length is less than the size of the area allocated at .ENTER 
time, the unused blocks are reclaimed as an empty area on the device. 

In magtape operations, the .CLOSE request causes the handler to write an 
ANSI EOFl label in software mode (using MM.SYS, MT.SYS, or MS.SYS) 
and to close the channel in hardware mode (using MMHD.SYS, 
MTHD.SYS, or MSHD.SYS). 

Errors: 

Code Explanation 

3 A protected file with the same name already exists on the 

device. The .CLOSE is performed anyway, resulting in two 
files with the same name on the device. 

.CLOSE does not return any other errors unless the .SERR request 
has been issued. If the device handler for the operation is not in 
memory, and the .CLOSE request requires updating of the device 
directory, a fatal monitor error is generated. 

Example: 

Refer to the examples for the .CSISPC and .WRITW requests, which 
show typical uses for .CLOSE. 

2.6 .CMKT (FB and XM. SJ Monitor Special Feature) 

The .CMKT request causes one or more outstanding mark time requests to 
be canceled (see the .MRKT programmed request). The .CMKT request is a 
special feature in the SJ monitor, and is selected with the timer support 
during the system generation process. 

Macro Call: .CMKT area,id[,time] 

where:. 

area is the address of a three-word EMT argument block 

id is a number that identifies the mark time request to be can- 

celed. If more than one mark time request has the same id, 
the request with the earliest expiration time is canceled. If 
id = 0, all non-system mark time requests (those in the 
range 1 to 176777) for the issuing job are canceled 
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time is the address of a two-word area in which the monitor re- 
turns the amount of time (clock ticks) remaining in the can- 
celed request. The first word contains the high-order time, the 
second contains the low-order. If an address of is specified, 
no value is returned. If id = 0, the time parameter is ig- 
nored and need not be indicated 

Request Format: 

RO — » area: 



23 



id 



time 



Notes: 

1. Canceling a mark time request frees the associated queue element. 

2. A mark time request can be converted into a timed wait by issuing a 
.CMKT followed by a .TWAIT, and by specifying the same time area. 

3. If the mark time request to be canceled has already expired and is 
waiting in the job's completion queue, .CMKT returns an error code of 
0. It does not remove the expired request from the completion queue. 
The completion routine will eventually be run. 

Errors: 

Code Explanation 

The id was not zero and a mark time request with the speci- 

fied identification number could not be found (implying that 
the request was never issued or that it has already expired). 

Example: 

Refer to the example for the .MRKT request. 

2.7 .CNTXSW (FB and XM Only) 

A context switch is an operation performed when a transition is made from 
running one job to running another. The .CNTXSW request is used to spec- 
ify locations to be included in a list when jobs are switched. Refer to the 
RT-11 Software Support Manual for further details. 

The system always saves the parameters it needs to uniquely identify and 
execute a job. These parameters include all registers and the following 
locations: 

34,36 Vector for TRAP instruction 
40-52 System Communication Area 

If an .SFPA request has been executed with a non-zero address, all floating- 
point registers and the floating-point status are also saved. 

It is possible that both jobs want to share the use of a particular location 
not included in normal context switch operations. For example, if a pro- 
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gram uses the lOT instruction to perform an internal user function (such as 
printing error messages), the program must set up the vector at 20 and 22 
to point to an internal lOT trap handling routine. If both foreground and 
background wish to use lOT, the lOT vector must always point to the 
proper location for the job that is executing. Including locations 20 and 22 
in the .CNTXSW list for both jobs before loading these locations accom- 
plishes this. This procedure is not necessary for jobs running under the XM 
monitor. In the XM monitor, both lOT and BPT vectors are automatically 
context switched. 

If .CNTXSW is issued more than once, only the latest list is used; the 
previous address list is discarded. Thus, all addresses to be switched must 
be included in one list. If the address (addr) is 0, no extra locations are 
switched. The list cannot be in an area into which the USR swaps, nor can 
it be modified while a job is running. 

In the XM monitor, the .CNTXSW request is ignored for virtual jobs, since 
they do not share memory with other jobs. For virtual jobs, the lOT, BPT, 
and TRAP vectors are simulated by the monitor. The virtual job sets up the 
vector in its own virtual space by any of the usual methods (such as a direct 
move or an .ASECT). When the monitor receives a synchronous trap from a 
virtual job that was caused by an lOT, BPT, or TRAP instruction, it checks 
for a valid trap vector and dispatches the trap to the user program in user 
mapping mode. An invalid trap vector address will abort the job with the 
following fatal error message: 

?MON-F-Inv SST (invalid synchronous system trap) 
Macro Call: .CNTXSW area,addr 
where: 

area is the address of a two- word EMT argument block 

addr is a pointer to a list of addresses terminated by a zero word. 
The addresses in the list must be even and be one of the 
following: 

a. in the range 2^76 

b. in the user job area 

c. in the I/O page (addresses 
160000-177776) 

Request Format: 

RO -^ area: 



33 







addr 



Errors: 



Code Explanation 

One or more of the conditions specified by addr was violated. 



Programmed Request Description and Examples 2-11 



Example: 



.TITLE CNTXSW.MflC 

h 

.CNTXSW - This is an example in the use of the .CNTXSW request. 

In this eKamplei a .CNTXSW resuest is used to specify that location 20 

and 22 (lOT ueotors) and certain necessary EftE resisters be context 

supitohed. This allows both Jobs to use IQT and the EftE simultaneously 
yet independently . 



.MCALL 



.CNTXSW (.PRINT ..EXIT 



START: 


.CNTXSW 


»AREA.«SWLIST 




BCC 


1$ 




.PRINT 


•ADDERR 




.EXIT 




It; 


.PRINT 
.EXIT 


sCNTDK 


SWLIST: 


.WORD 


20 




.WORD 


22 




.WORD 


177302 




.WORD 


17730a 




.WORD 


177310 




.WORD 





AREA: 


.BLKW 


2 


ADDERR: 


.ASCIZ 


/? .CNTXSW Ad 


CNTOK: 


.ASCIZ 


/.CNTXSW Suoc 



ilssue the .CNTXSW re-iuest 

iBranch if successful 

iAddress error (should not occur) 

iEk i t the p roSram 

iAcknowledde success with a messaSe 

ithen exit the prosram 

iAddresses to include in context switch 
1 lOT & EAE vectors. . . 
iEAE registers... 



iList terminator !M 
iEMT argument blocK 



.END 



START 



2.8 .CRAW (XM Only) 



The .CRAW request defines a virtual address window and optionally maps 
it into a physical memory region. Mapping occurs if you set the WS.MAP 
bit in the last word of the window definition block before you issue .CRAW. 
Since the window must start on a 4K word boundary, the program only has 
to specify which page address register to use and the window size in 32- 
word increments. If the new window overlaps previously defined windows, 
those windows are eliminated before the new window is created (except the 
static window reserved for a virtual program's base segment). 

Macro Call: .CRAW area,addr 



where: 



area is the address of a two-word EMT argument block 

addr is the address of the window definition block 

The window status word (W.NSTS) of the window definition 
block may have one or more of the following bits set on return 
from the request: 

WS.CRW set if address window was successfully created 
WS.VNM set if one or more windows were unmapped to 

create and map this window 
WS.ELW set if one or more windows were eliminated 
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Request Format: 
RO — * area: 

Errors: 



36 



addr 



Code Explanation 

Window alignment error: the new window overlaps the 
static window for a virtual job. The window is too large or 
W.NAPR is greater than 7. 

1 An attempt was made to define more than seven windows in 
your program. You should eliminate a window first 
(.ELAW), or redefine your virtual address space into fewer 
windows. 

If the WS.MAP bit was set in the window definition block status word, the 
following errors can also occur: 

Code Explanation 

2 An invalid region identifier was specified. 

4 The combination of the offset into the region and the size of 

the window to be mapped into the region is invalid. 

Example: 

.TITLE XMCOPY 

; + 

i This is an example in the use of the RT-11 EKtended Memopy requests. 
; The F>ro9raiii is a file copy with uerify utility that uses extended 
i memory to implement 4k transfer bufferst The example utilizes most of 
i the Extended Memory requests and demonstrates other proSrammins 
i techniques useful in utilizing the requests. 



.NLIST 

.MCflLL 

.MCALL 

JSM 

J.yiRT 

ERRBYT 

ftPR 

fiPRl 

euF 

BUFl 

CORSIZ 

PAGSIZ 

NRNID 

MRNIDl 



BEX 

.UNMflP 

.RDBBK 

44 



. ELRG , , ELAW . . CRRG i . CRAW .. MflP ., PRINT .. EX IT .. CLOSE 
. WDBBK ..TTYQUT i.WDBDF i , RDBDF . . CSIGEN , . READW . . WRITW 
iJSW location 
!>.<irtual Job bit in JSW 
iError byte location 
iPAR/PDR far Ist window 



2000 

5Z 

2 

4 

WDB+W.NBAS 

WDBl+W.NBAS 

409B. 

CDRSIZ/Z56. 

WDB+W.NRID 

WDBl+W.NRID 



, ASECT 

= JSW 
■WORD J.yjRT 
. PSECT 

. WDBDF 
.RDBDF 



) 



iy i rt ual 



" Znd 
addr of 



1st buf f e r 

! Znd 

iSize of buffer in words 
; Paste size in blocKs 
iRe^ion ID addr of 1st resion 
i Znd 

iAssemble in the ^lirt Job Bit 

!MaKe this a " virtual " Job 
iStart code now 

iCreate Window Def BIK Symbols 
i " Re9ion " " " 



START: i 



.CSIGEN 
BCS 



»ENDCRE.«DEFLT.«0 
START 



iGet filespeosf handlers 
iB ranch if error 



open files 
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INCB ERRNO 

.CRRG «CAREA.»RDB 

BCC 10* 

JMP ERROR 

10$: MOV RDBiWRNID 

INCB ERRNO 

.CRflW «CflREfl.«WDB 

BCC 20* 

JMP ERROR 

20$: INCB ERRNO 

.MAP «CAREA,«WDB 

BCC 30* 

JMP ERROR 

30$: CLR Rl 

MOy «C0RSIZiR2 

INCB ERRNO 

READ: .READW wRAREfl i»3 ,BUF .R2 iRl 

BCC WRITE 

TSTB S»ERRBYT 

BEO PASS2 

JMP ERROR 

WRITE: MOW RO .R2 

.WRITW «RAREAi«0.5UF,R2iRl 

BCC ADDIT 

INCB ERRNO 

JMP ERROR 

ADDIT: ADD "PAGSIZiRl 

BR READ 

PASS2: INCB ERRNO 

•CRRG »CAREAf«RDBl 

BCC 35* 

JMP ERROR 

35$: MOI.I RDBl iWRNIDl 



ERR = Ix 

Create a region 

Branch if successful 

Report error (JMP due to ranse!) 

Mcue resrion id to Windoy Def BIK 

ERR = Zk 

Create window. . • 

B ranch if no error 

Report e r ro r 1 • • 

ERR = 3k 

Explicitly map window><> 

Branch if no error 

Report error 

Rl = RTU Block « for I/O 

R2 = * of wards to read 

ERR = 4x 

Try to read 4K worth of blooKs 

Branch if no error 

EOF? 

Branch if yes 

Must be hard errori report it 

R2 = size of buffer Just read 

Mrite out the buffer 

B ranch if no error 

ERR = 5x 

Report error 

Adjust block • 

Then so set another buffer 

ERR = Bk 

Create a re aion 

Branch if no error 

Repo rt error 

Get re9ion id to window def blK 



i* EXAMPLE USING THE .CRAW REQUEST DOING 
i» IMPLIED .MAP REQUEST. 





INCB 


ERRNO 




.CRAW 


«CAREA>»WDB1 




BCC 


VERIFY 




JMP 


ERROR 


VERIFY:,: 


INCB 


ERRNO 




CLR 


Rl 


GETBLK: 


MOV 


•C0RSIZ.R2 




.READW 


sRAREAi«3.BUFl .R2iRl 




BCC 


ao$ 




TSTB 


e»ERRBYT 




BEO 


ENDIT 




JMP 


ERROR 


40$: 


MOV 


R0,R2 




.READW 


«RAREA,»0,BUF.RZ.R1 




BCC 


50$ 




INCB 


ERRNO 




JMP 


ERROR 


50$: 


MOV 


BUF .R4 




MOV 


BUFl .R3 


70$: 


CMP 


(Ra)+.(R3)+ 




BNE 


ERRDAT 




DEC 


R2 




BNE 


70$ 




ADD 


oPAGSIZ.Rl 




BR 


GETBLK 


ENDIT: 


.PRINT 


•ENDPRG 


XCLOS: 


.CLOSE 


«0 




.UNMAP 


«CAREA>ttWDB 




.ELAW 


«CAREA,«WDB 




.ELRG 


•CAREA>»RDB 




.ELRG 


«CAREAi«RDBl 




.EXIT 





iERR = 7x 

iCreate window usinsr implied .MAP 

{Branch if no error 

iRepo rt error 

iERR = 8x 

iRl = RTil block tt aSain 

iR2 - lik buffer size 

iTry to Set flK worth of input file 

(Branch if no error 

iEOF? 

{Branch if yes 

iRepo rt hard error 

;R2 = size of buffer read 

iTry to Set same size from output file 

iBranoh if no error 

iERR = 3x 

iRePO rt error 

iGet output buffer address 

iGet input buffer address 

iVerify that data is the same 

ilt's not I report error 

iAre we finished? 

iBranoh if we aren't 

iAdJust block « for paSe size 

iGo set another buffer pair 

{Announce we're finished 

i Close output file 

{Explicitly unmap 1st window 

{Explicitly eliminate 1st window 

{Eliminate 1st resion 

{Unmap .e 1 iminate 2nd window & reSion 

{Exit p rosram 
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ERROR: 



ERRDAT: 



RDB: 
MDB: 
RDBl: 
MDBl: 

CAREA: 

RAREA; 

DEFLT: 

ENDPRG; 

ERRs 

ERRNO; 

ERRBUFi 

ENDCRE 



MOUB 

ADD 

MOVB 

.PRINT 

BR 

•PRINT 

BR 

.RDBBK 
.kIDBBK 
.RDBBK 
.MDBBK 

.BLKM 

.BLKM 

.UDRD 

.A5CIZ 

.ASCII 

.ASCIZ 

.ASCIZ 



.END 



e«ERRBYT.RO 

«'0.R0 

RO.ERRNO+1 

• ERR 

XCLDS 

•ERRBUF 

XCLOS 



SMaKe error bfte code 2nd diait 

iof error code . . . 

iPut it in error message 

iPrint i t . . . 

iGo close output file 

iReport. uerify failed... 

;Go close output file 



CORSIZ/32. i.RDDBK defines Region Def Blk 

APR iC0RSIZ/3Z. i.UDDBK defines Mindou Def BIK 

C0RSIZ/3Z. iDefine 2nd reiion same way 

APRl .CDRSIZ/3Z. .0 lO tCDRSIZ/32. iWS.MAP i and 2nd Window 

i(but with mapping status set!) 
2 SENT argument blocKs 

6 

lO lO >0 iNo default extensions 

/ * End of XM Example Program ♦/ 
/?XM Request or I-O Error • / 
/OO/ 
/?Data yerifioation Error?/ 

iFor CSIGEN - XM handlers loaded 

START 



2.9 .CRRG (XM Only) 



The .CRRG request directs the monitor to allocate a dynamic region in 
physical memory for use by the current requesting program. 



Macro Call: 
where: 

area 
addr 



.CRRG area,addr 



is the address of a two- word EMT argument block 

is the address of the region definition block for the region to 
be created 



Request Format: 
RO -^ area: 

Errors: 



36 



addr 



Code Explanation 

6 No region control blocks are available. You eliminate a re- 
gion to obtain a region control block (.ELRG), or you can 
redefine your physical address space into fewer regions. 

7 A region of the requested size cannot be created because not 
enough memory is available. The size of the largest avail- 
able region is returned in RO. 

10 An invalid region size was specified. A value of 0, or a value 

greater than the available amount of contiguous extended 
memory, is invalid. 

Example: 

Refer to example for the .CRAW request. 
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2.10 .CSIGEM 

The .CSIGEN request calls the Command String Interpreter (CSI) in gen- 
eral mode to process a standard RT-11 command string. In general mode, 
file .LOOKUP and .ENTER requests as well as handler .FETCH requests 
are performed. 

The .CSIGEN request accepts a command string of the form dev:output- 
filespec = dev: input -filespec/ options, and the following operations occur: 

1. The handlers for devices specified in the command line are fetched. 

2. .LOOKUP and/or .ENTER requests on the files are performed. 

3. The option information is placed on the stack. See the end of this sec- 
tion for a description of the way option information is passed. Note that 
this call always puts at least one word of information on the stack. 

When called in general mode, the CSI closes channels through lO(octal). 

.CSIGEN loads all necessary handlers and opens the files as specified. The 
area specified for the device handlers must be large enough to hold all the 
necessary handlers simultaneously. If the device handlers exceed the area 
available, your program can be destroyed. (The system, however, is pro- 
tected.) 

The three possible output files are assigned to channels 0, 1, and 2, and the 
six possible input files are assigned to channels 3 through lO(octal). A null 
specification causes the associated channel to remain inactive. For exam- 
ple, the following string 

* .LP:=F1 .FZ 

causes channel to be inactive since the first specification is null. Channel 
1 is associated with the line printer, and channel 2 is inactive. Channels 3 
and 4 are associated with two files on DK:, while channels 5 through 10 are 
inactive. Your program can determine whether a channel is inactive by 
issuing a .WAIT request on the associated channel, which returns an error 
if the channel is not open. 

Macro Call: .CSIGEN devspc,defext[,cstrng][,linbuf] 

where: 

devspc is the address of the memory area where the device han- 
dlers (if any) are to be loaded 

defext is the address of a four-word block that contains the Ra- 
dix-50 default file types. These file types are used when a 
file is specified without a file type (see Note 1) 

cstrng is the address of the ASCIZ command string or a if input 
is to come from the console terminal. (In an FB or XM envi- 
ronment, if the input is from the console terminal, an .UN- 
LOCK of the USR is automatically performed while the 
string is being read, even if the USR is locked at the time.) 
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If the string is in memory, it must not contain a (Es) © (octal 
15 and 12), and must terminate with a zero byte. If the 
cstrng field is blank, input is automatically taken from the 
console terminal. This string, whether in memory or en- 
tered at the console, must obey all the rules for a standard 
RT-11 command string 

linbuf is the storage address of the original command string. This 
is a user-supplied area, 81 decimal bytes in length. The 
command string is terminated with a zero byte. If this argu- 
ment is omitted, the input command string is not copied to 
user memory 

On return, RO points to the first available location above the handlers, the 
stack contains the option information, and all the specified files have been 
opened. 

Note: 

1. The four- word block pointed to by defext is arranged as: 

Word 1: default file type for all input channels (3-10) 

Words 2,3,4: default file types for output channels 0, 1, and 2, 
respectively 

If there is no default for a particular channel, the associated word must 
contain 0. All file types are expressed in Radix-50. For example, the 
following block can be used to set up default file types for a macro 
assembler: 

DEFEXT: .RAD50 "MAC" 

,RAD50 "OBJ" 

,RAD50 "LBT" 

.WORD 

In the command string: 

*DTO! ALPHA ,DT1 : BET A = DTZ! INPUT 

the default file type for input is MAC; for output, OBJ and LST. The 
following cases are valid: 

*DTO:OUTPUT= 
#DT2!lNPUT 

In other words, the equal sign is not necessary if only input files are 
specified. 

2. An optional argument {linbuf) is available in the .CSIGEN format that 
provides the user with an area to receive the original input string. The 
input string is returned as an ASCIZ string and can be printed through 
a .PRINT request. 

3. The .CSIGEN request automatically takes its input line from an indi- 
rect command file if console terminal input is specified (cstrng = #0) 
and the program issuing the .CSIGEN is invoked through an indirect 
command file. 
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Errors: 



If CSI errors occur and input was from the console terminal, an error 
message describing the fault is printed on the terminal and the CSI 
retries the command. If the input was from a string, the carry bit is 
set and byte 52 contains the error code. In either case, the options and 
option-count are purged from the stack. These errors are: 

Code Explanation 

Invalid command (such as bad separators, invalid file 
names, and commands that are too long). 

1 A device specified is not found in the system tables. 

2 A protected file of the same name already exists. A new file 
was not opened. 

3 Device full. 

4 An input file was not found in a .LOOKUP. 



Example: 



.TITLE 



GSIGEN.MAC 



.CSIGEN - This is an example in the use of the .CSIGEN request. 

The example is a single file copy prosrram. The file specs are 

input from the console terdtinalf and the input & output files opened 

uia the General mode of the CSI. The file is copied usin3 s/nohrcnous 

I/O) and the output file is made perfiianent uia the .CLOSE request. 

.MCALL .CSIGEN , . READW . . EX I T . . WR I TW . , CLOSE . . SRESET 





ERRBYT= 


52 


START: 


.CSIGEN 


sDSPACE.KDEXT 




MOV 


ROiBUFF 




CLR 


INBLK 




MOM 


«LIST,R5 


READ: 


.READU 


R5.»3.BUFF,»25G, 




BCC 


2» 




TSTB 


S»ERRBYT 




BED 


EOF 




Moy 


• INERRiRO 


It: 


.PRINT 






CLR 


RO 




.EXIT 




2$: 


.WRITW 


R5,»0,BUFF.«256. 




BCC 


NOERR 




Moy 


•WTERR.RO 




BR 


It 


NDERR: 


INC 


INBLK 




BR 


READ 


EOF: 


.CLOSE 


• 




.CLOSE 


«3 




.SRE3ET 






.EXIT 




DEXT: 


.WORD 


>0 lO lO 


BUFF: 


.MORD 





INBLK: 


.WORD 





LIST: 


.BLKW 


5 



.INBLK 



iINBLK 



lE r ro p Byte Location 

Get strins from terminal 

RO has first free location 

-Input blocK # 

EMT Argument list 

Read a blocK on Channel 3 

Branch if nc errors 

EOF error ? 

Yes. . . 

RO => Read Error Message 

Print the message 

Clear RO for hard exit 

Exit the program 

Write the blooK Just read 

Branch if no error 

RO => Write error messaaie 

Branch to output the messasre 

Otheruisei increment blocK « 

and loop to read next blocK 

End-of -Fi le . . iCLose output channel 

And input ohanne 1 

Release handler(s) from memory 

Exit the pros ram 

iNo default extensions 

iI/0 Buf f e r start 

iRelatiue block to read/urite 

iEMT argument list 



INERR: 



.ASCIZ 



/? Input error ?/ 
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WTERR: 



.ASCIZ 
.EVEN 



/? Output error ?/ 



DSPACE 



iHandler(s) can be loaded starting here 



.END 



START 



2.10.1 Passing Option information 

In both general and special modes of the CSI, options and their associated 
values are returned on the stack. A CSI option is a slash (/) followed by any 
char-acter. The CSI does not restrict the option to printing characters, al- 
though you should use printing characters to avoid confusion. The option 
can be followed by a value, which is indicated by a : separator. The : separa- 
tor is followed by an octal number, a decimal number, or by one to three 
alphanumeric characters, the first of which must be alphabetic. Decimal 
values are indicated by terminating the number with a decimal point 
(/N:14.). If no decimal point is present, the number is assumed to be octal. 
Options can be associated with files. For example, the command string 

*DK:FaO/A»DTa:FILE.OBJ/A!lOO 

has two A options. The first is associated with the input file DK:FOO. The 
second is associated with the input file DT4:FILE.0BJ and has a value of 
lOO(octal). The format of the stack output of the CSI for options is as fol- 
lows: 



Word# 

1 
(top of 

stack) 



Value Meaning 

N Number of options found in command 

string. If N = 0, no options were found. 



Option character Even byte 
and file number 

Bits 8-14 



Bit 15 



seven-bit ASCII option 
character 

number (0-10) of the file 
with which the option is 
associated 

1 if the option had a 
value 

if the option had no 
value 



Option value 
or next option 



If bit 15 of word 2 is set, word 3 contains 
the option value. If bit 15 is not set, word 3 
contains the next option character and file 
number, if any. 



For example, if the input line to the CSI is 

*FILE/B!20. tFIL2/E=DT3! INPUT/X : SY : 20 
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on return, the stack is: 



Stack Pointer 



101530 

20 

101530 

075250 

505 

100102 

24 



Three options appeared (X option has two 

values and is treated as two options). 

Last option = X; with file 3, has a value. 

Value of option X = 20(octal). 

Next option =X; with file 3, has a value. 

Next value of option X = RAD50 code for 

SY. 

Next option = E; associated with file 1, no 

value. 

Option = B; associated with file and has 

a value of 24. 

(octal). 



As an extended example, assume the following string was input for the CSI 
in general mode: 

*FILE[8. ] iLPi .SY:FILE2[20. ] = PC: »DT 1 : IN 1 /B .DTZ ! I N2/M : 7 

Assume also that the default file type block is: 



DEFEXT: 


.RAD50 


'MAC 




.RAD50 


'OPl ' 




.RAD50 


'0P2' 




.RAD50 


'0P3' 



UNPUT FILE TYPE 
;FIRST OUTPUT FILE TYPE 
;SECOND OUTPUT FILE TYPE 
iTHIRD OUTPUT FILE TYPE 



The results of the above CSI call are as follows: 

1. An eight-block file named FILE. OPl is entered on channel on device 
DK:; channel 1 is open for output to the device LP:; a 20-block file 
named FILE2.0P3 is entered on the system device on channel 2. 

2. Channel 3 is open for input from device PC:; channel 4 is open for input 
from a file INI. MAC on device DTI:; channel 5 is open for input from 
IN2.MAC on device DT2:. 

3. The stack contains options and values as follows: 

Contents Explanation 

2 Two options found in string. 

102515 Second option is M, associated with channel 5; has a value. 

7 Numeric value is 7(octal). 

2102 Option is B, associated with channel 4; has no value. 

If the CSI were called in special mode, the stack would be the same as for 
the general mode call, and the descriptor table would contain: 



OUTSPC: 


15270 


.RAD50 




'DK ' 




233B4 


.RAD50 




'FIL' 




17500 


.RAD50 




'E' 




G0137 


.RAD50 




'OPl ' 




10 


LENGTH 


OF 


8 BL 




^GGOO 


.RAD50 




'LP' 
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; 


NO NAME OR 


LEN 


GTH SPEC 























75250 i 


,RAD50 


SY' 


23364 i 


.RAD50 


FIL' 


22100 i 


.RAD50 


E2' 


G0141 i 


.RAD50 


0P3' 


za i 


LENGTH OF 


20 (DECIMAL) 


G2170 


.RAD50 


PC 





NO NAME SPECIFIED 
















16077 


.RAD50 


DTI 




35217 


.RAD50 


INI 







.RAD50 






50553 


.RAD50 


MAC 




IGIOO 


,RAD50 


DT2 




35220 


.RAD50 


IN2 







.RAD50 






50553 


.RAD50 


MAC 












(12 more zero words are returned) 



Keyboard error messages that can occur when input is from the console 
keyboard include: 



Message 

?CSI-F-Invalid command 
?CSI-F-file not found 
?CSI-F-Device full 
?CSI-F-Invalid device 
?CSI-F-Protected file 



Meaning 

Syntax error. 
Input file was not found. 
Output file does not fit. 
Device specified does not exist. 
Output file specified already 
exists and is protected. 



Notes: 



In many cases, your program does not need to process options in CSI 
calls. However, you could inadvertently enter options at the console. In 
this case, it is wise to save the value of the stack pointer before the call 
to the CSI, and restore it after the call, so that no extraneous values are 
left on the stack. Note that even a command string with no options 
causes a word to be pushed onto the stack. This word indicates the 
number of options to follow. 

Under an FB monitor, calls to the CSI that require console terminal 
input always do an implicit .UNLOCK of the USR while the string is 
being gathered. This should be kept in mind when using .LOCK calls. 



2.11 .CSISPC 



The .CSISPC request calls the Command String Interpreter in special mode 
to parse the command string and return file descriptors and options to the 
program. In this mode, the CSI does not perform any .CLOSE, .ENTER, 
.LOOKUP, or handler .FETCH requests. 
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Options and their associated values are returned on the stack. The optional 
argument {linbuf) can provide your program with the original command 
string. 

.CSISPC automatically takes its input line from an indirect command file if 
console terminal input is specified (cstrng = #0) and the program issuing 
the .CSISPC is invoked through an indirect command file. 

Note that in a foreground/background environment, calling the CSI per- 
forms a temporary and implicit .UNLOCK while the command line is being 
read. 

Macro Call: .CSISPC outspc,defext[,cstrng][,Hnbufl 

where: 

outspc is the address of the 39-word block to contain the file 
descriptors produced by .CSISPC. This area can overlay the 
space allocated to cstrng, if desired 

defext is the address of a four-word block that contains the Ra- 
dix-50 default file types. These file types are used when a 
file is specified without a file type 

cstrng is the address of the ASCIZ input string or a #0 if input is 
to come from the console terminal. If the string is in mem- 
ory, it must not contain a (eUl © (octal 15 and 12), and must 
terminate with a zero byte. If cstrng is blank, input is auto- 
matically taken from the console terminal or indirect file, if 
one is active 

linbuf is the storage address of the original command string. This 
is a user-specified area, 81 bytes in length. The command 
string is terminated with a zero byte instead of ® © (octal 
15 and 12) 

Notes: 

1. The file description consists of 39 words, comprising nine file descriptor 
blocks (five words for each of three possible output files; four words for 
each of six possible input files), which correspond to the nine possible 
files (three output, six input). If any of the nine possible file names are 
not specified, the corresponding descriptor block is filled with zeroes. 

2. The five-word blocks hold four words of Radix-50 representing 
dev: file. type, and one word representing the size specification given in 
the string. (A size specification is a decimal number enclosed in square 
brackets ([ ]) that follows the output file descriptor.) For example: 

*DT3:LIST.MACC15]=PC: 

Using special mode, the CSI returns in the first five-word slot: 

16101 Radix-50 for DT3 

46173 Radix-50 for LIS 

76400 Radix-50 for T 

50553 Radix-50 for MAC 

00017 Octal value of size request 
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In the fourth slot (starting at an offset of 36 bytes [octal] into outspc), 
the CSI returns: 

62170 Radix-50 for PC 

No file name 
specified 

No file type given 

Since this is an input file, only four words are returned. 

Errors: 

Errors are the same as in general mode except that invalid device 
specifications are checked only for output file specifications with null 
file names. Since .LOOKUP and .ENTER requests are not done, the 
valid error codes are: 




1 

Example: 



Code Explanation 

Invalid command line. 
Invalid device. 



.TITLE CSISPC.MAC 

.CSISPC - This is an eKample in the use of the .CSISPC request. 
The example uses the "special" mode of CSI to Set an input 
specification from the console terminal) then uses the .DSTATUS 
request to determine if the output deuioe's handler is loaded! 
if not I a .FETCH request is issued to load the handler into 
memory. Finally a .DELETE reiuest is issued to delete the specified 
file. 



.MCALL 



.DSTATUS ..PRINT , .EXIT .. FETCH .. CSISPC ,, DELETE 



START! 



MOy SP. R5 

.CSISPC ttOUTSP.sDEFEXT 

MOy R5. SP 

.DSTAT »STAT(«OUTSP 





TST 


STAT+a 




BNE 


Z» 




.FETCH 


SHANLOD.WINSPEC 




BCC 


2* 




.PRINT 


SFEFAIL 




.EXIT 




2$: 


.DELETE 


«AREA.«Ot»INSPEC 




BCC 


3* 




.PRINT 


»NOFIL 




BR 


START 


3t! 


.PRINT 
.EXIT 


SFILDEL 


AREA! 


.BLKW 


2 


STATi 


.BLKW 


a 


DEFEXT! 


.UORD 


lO »0 .0 


FEFAILi 


.ASCIZ 


/?. FETCH Failed?/ 


NOFIL! 


.ASCIZ 


/?File Not Found?/ 


FILDEL! 


.ABCIZ 
.EVEN 


/IFile Deleted! / 


DUTSP! 


,BLKW 5*3 




INSPEC! 


.BLKW 4*S 




HANLDD: 


.BLKW 1 





SSaue current stack pointer 

iUse .CSISPC to Set output spec 

iRestore SP to clear any CSI options 

iCheoH on the output deuioe 

!<CSISPC catches illesal devices!) 

iSee if the deuice is resident 

iBranch if already loaded 

ilt's not loaded .. .b rins it into memory 

iBranch if successful 

iFetch f ai led . . . p rint error messaSe 

i then exit proSram 

iNou delete the file 

iBranch if successful 

iPrint error messaSe 

iThen try aJain 

iAcknouledSe successful deletion 

ithen exit pros ram 

lEMT ArSument blooK 
iBlocK for status 
iNo default extensions 
iFetch failed messaSe 
!File not found 
iDelete acKnowl edsment 
iFix boundary 

iOutPUt specs so here 

ilnput specs So here 

iHandlers besin loadins here (if necessary) 



.END 



START 
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2.12 .CSTAT 

This request furnishes you with information about a channel. 

Macro Call: .CSTAT area,chan,addr 

where: 

area is the address of a two-word EMT argument block 

chan is the number of the channel about which information is de- 
sired 

addr is the address of a six-word block to contain the status 
Request Format: 

RO -* area: 



27 chan 



addr 



Notes: 

The six words passed back to the user correspond to the following six points 
of information: 

1. Channel status word (see the RT-11 Software Support Manual for de- 
tails) 

2. Starting block number of file (0 if sequential-access device, or if channel 
was opened with a non-file-structured .LOOKUP or .ENTER) 

3. Length of file (0 if non-file-structured device, or if channel was opened 
with a non-file-structured .LOOKUP or .ENTER) 

4. Highest relative block written since file was opened (no information if 
non-file-structured device). This word is maintained by the 
.WRITE/.WRITC/.WRITW requests 

5. Unit number of device with which this channel is associated 

6. Radix-50 of the device name with which the channel is associated (this 
is a physical device name, unaffected by any user name assignment in 
effect). 

Errors: 

Code Explanation 

The channel is not open. 
Example: 

.TITLE CSTflT.MftC 

h 

.CSTAT - This is an example in the use of the .CSTflT request. 
In this examplei .CSTAT is used to determine the .RADSO 
representation of the deuice with which the channel is associated. 

.MCALL . CSTAT.. CS I GEN . . PRINT , . EX I T 

START! MOy SP) R5 iSaue current stack painter 

.CSIGEN •DEVSDC.sDEFEXT iOpen files 

MOy R5 ' SP iRestore SP to clear any CSI options 

.CSTAT »AREA.»0 .SADDR iGet the status 

BCS NOCHAN iChannel not open 

MCV «ADDR+10,R5 iPoint to unit » 
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MOy 


(R5)+ iRO 


iUnlt » to RO 




ADD 


(PC)+ iRO 


iMaKe it RAD50 




,RAD50 


/ 0/ 






ADD 


(R5) iRO 


SGet device ratne 




MOU 


ROrDEWNAM 


i'DEVNAM' has RAD50 deuioe name 




.EXIT 




iE« 1 1 the p roSram 


NOCHflN: 


.PRINT 


»MSG 


iPrint error messaSe 




.EXIT 




ithen exit prosram 


MSG! 


.ASCIZ 


/?No Output File' 


'/ JError message 




.EVEN 




iFix boundary 


AREA: 


.BLKW 


5 


iEMT ars list 


ADDRs 


.BLKW 


B 


lArea for channel status 


DEyNAM: 


.WORD 





iStoraSe for deuioe name 


DEFEXT: 


.WORD 


lO lO lO 


iNo default extensions 


DEySDC=. 






iStart CSI tables here... 



.END 



START 



2.13 .CTIMIO (Device Handler Only) 

The .CTIMIO macro cancels the device time-out request in the handler 
interrupt service section. It is used when an interrupt occurs to disable the 
completion routine (see .TIMIO). 

If the time interval has already elapsed and the device has, therefore, timed 
out, the .CTIMIO request fails. The completion routine has already been 
placed in the queue. The .CTIMIO call returns with the C bit set when it 
fails because the completion routine was already queued. 

The device time-out feature must have been selected during the system 
generation process. 

Macro Call: .CTIMIO tbk 



where: 

tbk 



is the address of the seven-word timer block shown in Table 
2-1 



Table 2-1: Timer Block Format 



Offset Filled in By 






.TIMIO 


2 


.TIMIO 


4 


monitor 


6 


user 



10 

12 
14 



user 

monitor 
user 



Contents 



High-order time word (expressed in ticks). 

Low-order time word (expressed in ticks). 

Link to next queue element; indicates none. 

Owner's job number; for background job, MAXJOB for fore- 
ground job, and job priority *2 for system jobs. MAXJOB is 
equal to (the number of jobs in the system * 2)-2. The job 
number for the foreground job is 2 in a system without system 
jobs, and 16 for a system with system jobs. The job number is 
set from the queue element. 

Sequence number of timer request. The valid range of sequence 
numbers is from 177000 to 177377. 

-1 

Address of the completion routine to execute if timeout occurs. 
The monitor zeroes this word when it calls the completion 
routine, indicating that the timer block is available for reuse. 
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The .CTIMIO macro expands as follows: 





.CTIMIO tbk 




JSR R5.@$TIMIT iPOINTER AT END OF 

.WORD tbk - . 

.WORD 1 iCODE FOR .CTIMIO 




Example: 




Refer to the example for the .TIMIO request 


.14 


.DATE 



This request returns the current date information from the system date 
word in RO. The date word returned is in the following format: 



BIT: 



15 14 13 ... 10 9 ... 5 4 







MONTH DAY YEAR 

The year value in bits 4-0 is the actual year minus 1972. The day in bits 9 
to 5 is a number from 1 to the length of the month. The month in bits 13 to 
10 is a number from 1 to 12. 

NOTE 

RT-11 support of month and year rollover is a system gener- 
ation special feature; otherwise, the keyboard monitor DATE 
command must be issued to change the month and year. 

Macro Call: .DATE 

Request Format: 

RO = 

Errors: 

No errors are returned. A zero result in RO indicates that the user has 
not entered a date. 

Example: 



12 



•TITLE DflTE.MAC 



•DATE - This is an example in the use of the .DATE request. 
This example may be assembled separately and linked with 
user written programs 



INPUT! 



OUTPUT! 



none 

RO = MONTH <1-1Z) 

Rl = DAY (1-31) 

RZ = YEAR (Last two disits) 



2-26 Programmed Request Description and Examples 



i ERRORS: 



RO 



if no date entered 



.MCALL 



.DATE 



DATE! 



1$! 



.DATE 




iGet date in RO wia .DATE request 


MOM 


R0,R2 


iCopy RO 


BEO 


It 


ilf zero> no date was entered 


BIC 


«-C37,RZ 


iClear all but year bits 


ADD 


«7Z. .RZ 


IMaKe it current year 


MOV 


ROtRl 


iCopy date word aSain 


ASL 


Ri 


iGet day bits 


ASL 


Rl 


ion a byte boundary... 


ASL 


Rl 


i 


SMAB 


Rl 


iPut day bits in low order byte 


BIC 


«-C37,Rl 


iClear aU but day bits 


SUAB 


RO 


iPut month bits in low byte 


ASR 


RO 


iRisht adjust 


ASR 


RO 


imonth bi ts . . . 


BIC 


«~C17.R0 


iClear all but month bits 


RETURN 




iReturn to callinS prosram 



.END 



2.15 .DELETE 



The .DELETE request deletes a named file from an indicated device. The 
.DELETE request is invalid for magtapes. The .SERR programmed request 
can be used to allow the program to process any errors. 

Macro Call: .DELETE area,chan,dblk[,seqnum] 

where: 

area is the address of a three-word EMT argument block 

chan is the device channel number in the range 0-376(octal) 

dblk is the address of a four-word Radix-50 descriptor of the 

file to be deleted 

seqnum file number for cassette operations: if this argument is 
blank, a value of is assumed 

Request Format: 

RO —> area: 

Notes: 

The channel specified in the .DELETE request must not be open when the 
request is made, or an error will occur. The file is deleted from the device, 
and an empty (UNUSED) entry of the same size is put in its place. A 
.DELETE issued to a non-file-structured device is ignored. .DELETE re- 
quires that the handler to be used be in memory at the time the request is 
made. When the .DELETE is complete, the specified channel is left inac- 
tive. 



chan 



dblk 



seqnum 
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Errors: 

Code 


1 
2 
3 
Example: 



Explanation 

Channel is active. 

File was not found in the device directory. 

Invalid operation. 

The file is protected and cannot be deleted. 



.TITLE DELETE. MAC 

h 

•DELETE - This is an example in the use of the .DELETE request. 
The example uses the "special" mode of CSI to Set an input 
specification from the console terminali then uses the .DSTATUS 
request to determine if the output device's handler is loaded; 
if not) a .FETCH request is issued to load the handler into 
memory. Finally a .DELETE request is issued to delete the specified 
file. 



.MCALL 



. DSTATUS .. PRINT .. EXIT . , FETCH . .CSISPC . .DELETE 



START: 


MOV 


SP. R5 




.CSISPC 


«OUTSP.»DEFEXT 




MOV 


R5, SP 




.DSTAT 


«STfiT ."DUTSP 




TST 


STAT+a 




SNE 


2* 




.FETCH 


•HANLOD. SINSPEC 




BCC 


2$ 




.PRINT 


ttFEFAIL 




.EXIT 




2*; 


.DELETE 


»AREA,«0,«INSPEC 




BCC 


3« 




.PRINT 


sNOFIL 




BR 


START 


3«! 


.PRINT 
.EXIT 


sFILDEL 


AREA: 


.BLKW 


2 


STAT: 


.BLKW 


a 


DEFEXT! 


.WORD 


0.0,0.0 


FEFfilL! 


.ASCIZ 


/?. FETCH Failed?/ 


NOFIL: 


.ASCIZ 


/?File Not Found?/ 


FILDEL: 


.flSCIZ 
.EVEN 


/!File Deleted!/ 


DUTSP: 


.BLKW 5*3 




INSPEC: 


.BLKW a*B 




HANLOD: 


.BLKW 1 






.END 


START 



SauB current stacK pointer 

Use .CSISPC to 9et output spec 

Restore SP to clear any CSI options 

CheoK on the output deuice 

(CSISPC catches illegal deuices!) 

See if the deuice is resident 

Branch if already loaded 

It's not loaded. i.brinil it into memory 

Branch if successful 

Fetch fai led ... p Tint error messase 

then exit p rcs( ram 

Nou delete the file 

Branch if successful 

Print error message 

Then try asain 

AcKnowledSe successful deletion 

then exit pros ram 

iEMT Arsument blooK 

iBlacK for status 

iNo default extensions 

iFetch failed message 
iFile not found 
■ Delete acKnoul ed <rmen t 
SFix boundary 

iOutput specs So here 

ilnput specs 9o here 

iHandlers besin loadinS here (if necessary) 



2.16 .DEVICE (FB and XM Only) 

This request allows your program to load device registers with any neces- 
sary values when the program is terminated. You set up the list of ad- 
dresses with the specified values. Upon issuing an .EXIT request or a 
CTRL/C from the terminal, this list is picked up by the system and the 
designated addresses are loaded with the corresponding values. This func- 
tion is primarily designed to allow your program to turn off a device's 
interrupt enable bit when the program servicing the device terminates. 



2-28 Programmed Request Description and Examples 



Successive calls to .DEVICE are allowed when you need to link requested 
tables. When the job is terminated for any reason, the list is scanned once. 
At that point, the monitor disables the feature until another .DEVICE call 
is executed. Thus, background programs that are reenterable should in- 
clude .DEVICE as a part of the reenter code. 

The .DEVICE request is ignored when it is issued by a virtual job running 
under the XM monitor. 

Macro Call: .DEVICE area,addr[,link] 

where: 

area is the address of a two-word EMT argument block 

addr is the address of a list of two-word elements, each composed of 
a one-word address and a one-word value to be put at that 
address. If addr is #0, any previous list is discarded; in this 
form, the argument link must be omitted 

link is an optional argument that, if present, specifies linking of 
tables on successive calls to .DEVICE. If the argument is 
omitted, the list referenced in the previous .DEVICE request 
is replaced by the new list. The argument must be supplied to 
cause linking of lists; however, linked and unlinked list types 
cannot be mixed 



Request Format: 

Nonlinking 


Linking 


RO -^ area: 


14 1 


RO -^ area: 


14 1 




addr 


addr 



NOTE 

The list referenced by addr must be in either linking or non- 
linking format. The different formats are shown below. Both 
formats must be terminated with a separate, zero-value 
word. Linking format must also have a zero-value word as its 
first word. 



Nonlinking 


Linking 


addr: 


address 


addr: 







value 


address 




address 


value 




value 


address 




• 


value 




• 




address 




value 




address 







value 
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Errors: 

None. 
Example: 



.TITLE DEVICE. MAC 



•DEVICE - This is an eKawple in the use of the .DEVICE reiuest. 
The example shouis hay .DEVICE is used to disable interrupts from 
a device upon termination of the program. In this case the deuice 
is a DLll Serial Line Interface. 





.MCALL 


.DEVICE. .EX 




.GLOBL 


DLll 


START; 


.DEVICE 


• AREA.ttLIST 




.PROTECT 


»AREA.»300 




BCS 
! 


BUSY 




1 

JSR 


R5.DL11 




.WORD 


128. 




.UORD 

i 


BUFFR 


FINl! 


! 

.UNPROTECT 

.EXIT 


«AREA.»300 


BUSY: 


.PRINT 
.EXIT 


■NOVEC 


AREA: 


.BLKM 


3 


LIST: 


.WORD 


176500 




.WORD 







.WORD 





BUFFR: 








.REPT 


8. 




.ASCIZ 


/Hello DLll 




.ENDR 




NOVEC: 


.ASCIZ 


/?Vector al 



DEVICE . .EXIT . . PROTECT . . UNPROTECT ,. PRINT 



iSetup to disable DLll interrupts on 

i.EXIT or "C"C 

iProteot the DLll vectors 

■Branch if already protected 

iSet UP data to transmit ouer DLll 

SUse DLll xfer routine (see . INTEN example) 

■ Arsruments . . . Wo rd count 
iData buffer addr 
iContinue processins. • . 

■ ...eventually to exit pro^lram 

iPrint error messase... 
i then exit 
!EMT Argument block 
!CSR of DLll 
iFi II it with '0 ' 
iList terminator 
iData to send over DLll 
iS lines of 32 characters... 
Are You There ??/ 



/?Vector already protected?/ iError message text 



.END 



START 



2.17 .DRAST (Device Handler Only) 

The .DRAST macro sets up the interrupt and abort entry points, lowers the 
processor priority, and references a global symbol $INPTR, which contains 
a pointer to the $INTEN routine in the resident monitor. This pointer is 
filled in by the bootstrap (for a system device) or at .FETCH time (for a data 
device). 

Macro Call: .DRAST name,pri[,abo] 

where: 

name is the two-character device name 

pri is the priority of the device, and also the priority at which 

the interrupt service code is to execute 

abo is an optional argument that represents the label of an abort 

entry point. If you omit this argument, the macro generates 
an RTS PC instruction at the abort entry point, which is the 
word immediately preceding the interrupt entry point 
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Example; 



.TITLE 



SP.MAC 



i + 

i SP.MAC - This is an example of a simplei RT-11 deuioe driuer to illustrate 
i the use of the .DRBEG. .DRflSTi .DRFIN. .DRENDi .FORK & .OELDF requests. 
i This driuer could be used to output to a serial ASCII prin t e r- t e rwinal 
i ouer a DLll Serial Line Interface. To use this driuer as an RT-11 deuioe 
i handleri siniplv install it uia the INSTALL command (e3. 'INSTALL SP'). 



.MCALL 



.DRBEG i.DRAST i.DRFINi . DREND i. OELDF ..FORK 



,IIF NDF MMG*T . 
. IIF NDF ERLtG . 
.IIF NDF TIM*IT, 



MMG«T=0 
ERL*G=0 
TIM*1T=0 



iDefine these in case not 
iassembled with SYSCND.MAC 



,IIF NDF SP*yEC. 
,IIF NDF SP«CSR. 
, IIF NDF BPtPRI . 



SP*VEC=304 

SP»CSR=178504 

SP*PRI=4 



iDefine default ueotor 
iDefine default CSR addr 
iDefine default deuioe priority 



lOERR = 1 

SPSTS = 20000 

iDeuioe Status = Write only 

SPSIZ = 



iHard I/O error bit definition 



iOeuice Size 



<Char deuioe) 



.OELDF 



iO.BLKN = a 
iOtCSW = -2 
iO*BUFF = a 
iOtWCNT = B 



iUse .OELDF to define O-Elem offsets 
iAmonS others & of interest to us ares 
iOffset to BlooK « (SPCOE => O.BLKN) 
iOffset from O.BLKN to CSW pointer 
i " " " " Userbufferptr 
i " " " " Word count 



.DRBEG 



i 


• WORD 


<SPEND-SPSTRT 


i 


.NORD 





i 


.WORD 


20000 


J 


.WORD 


ERL*G+<MMGtT« 


iSPSTRT: 






i 


.WORD 


SPyEC+4 


i 


.WORD 


SPINT-. ."0340 


iSPCOE:: 


.WORD 





iSPLOE; : 


.WORD 







MOV 


SPCOE iRa 




ASL 


DtWCNT(Ra) 




BCC 


SPERR 




BEO 


SPDUN 


SPRET! 


BIS 
RETURN 


«100 ie»tSP$CSR 



SP.SPfOECiSPSIZ. SPSTS iBeSin driuer code with .DRBEG 
iMfiCRO expansion is... 
iSize of driuer (handler) 
iSize of deuice 
iDeuioe status (Write only) 
TIM$IT»a> iOef aul t options 
iBe Sinn ins of driuer 
ilnterrupt ueotor 

iOffset to Int sue rtne & Priority 
i u e u e element pointers 
i(Point to 3rd word in element!) 
iRa => Current 0-Element 
iMaKe word count byte count 
iA read from a write/only deuioe? 
iZero word count. ..Just exit 
iEnable DL-11 interrupt 
{Return to monitor 



i INTERRUPT SERVICE ROUTINE 





.DRAST 


i 


RTS 


iSPINT: 


! JSR 


i 


.WORD 




MOV 




TST 




BMI 




BIC 




.FORK 


SPNXT: 


TSTB 




BPL 




MOVB 




INC 




INC 




BEO 




BR 


SPERR! 


BIS 


SPDUN: 


.DRFIN 



SP.SPJPRI iUse .DRAST to define Int Sue Sect. 

iMACRD expansion... 

PC iAbort Entry Point 

R5(@*INPTR iDo a .INTEN to alert monitor 

"C<SPtPRI»"0a0>&''03a0 land drop processor priority 

SPCOEiRa iRa => 0-Element 

@»SP$CSR iError? 

SPRET i Yes . . . 'hans ' until ready 

• 100 )e»3P*C9R {Disable interrupts 

SPFORK iContinue at FORK leuel 

(a«SP*CSR ils deuioe ready? 

SPRET iNo...so wait 'till it is 
(ao«BUFF(Ra) i@»SPtCSR + 2iXf er byte from buffer to DL-11 

0*BUFF(Ra) iBump the buffer pointer 

0*WCNT(Ra) iand the word count (it's nesfatiue!) 

SPDUN iBranoh if done 

SPNXT iTry to output another character 



«IOERR.@OtCSW(Ra) 
SP 



iSet error bit in CSW 

iUse .DRFIN to return to Monitor 

IMACRO expansion... 
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Moy 


PC .R4 




ADD 


SSPCOE-. .R 




Moy 


e«5a.R5 




MP 


B'D270(R5) 


SPFDRK: 


.WORD 


lO lO lO 




.DREND 


BP 


itlNPTR: 


: .WORD 





i*FKPTR: 


: .WORD 





iSPEND = 


= , 





iCaloulate PIC addr of current 

!queue elBMent pointer 

!Put addr of base of RMON in R5 

iJump to handler ooitipletion in Monitor 

jForK Queue Eledient 

iUse .DREND to end oode 

5MACR0 expansion... 

iAddr of .INTEN code in RMON 

iAddr of .FORK processor in RMON 

!End of driuer 



.END 



2.18 .DRBEG (Device Handler Only) 

The .DRBEG macro sets up the information in block and the first five 
words of the handler. This macro also generates the appropriate global 
symbols for your handler. Before you use .DRBEG, invoke .DRDEF to de- 
fine xx$CSR, xx$VEC, xxDSIZ, and xxSTS (see Section 2.20). 

Macro Call: .DRBEG name 

where: 

name is a two-character device name 
Example: 

Refer to the example for .DRAST. 



2.19 .DRBOT (Device Handler Only) 

The .DRBOT macro sets up the primary driver. A primary driver must be 
added to a standard handler for a data device to create a system device 
handler. The .DRBOT macro invokes the .DREND macro (see Section 2.21) 
to mark the end of the handler so that the primary driver is not loaded into 
memory during normal operations. 

Macro Call: .DRBOT name,entry,read[,CONTROL = arg...,arg][,SIDES = n] 
where: 



name 
entry 
read 
CONTROL 



SIDES 



is the two-character device name 

is the entry point of the software bootstrap routine 

is the entry point of the bootstrap read routine 

defines the types of controllers supported by this han- 
dler. The values for arg can be UBUS or QBUS. If 
CONTROL is omitted, both Unibus and Q-bus are as- 
sumed. This is correct for all supported handlers 

specifies single- or double-sided diskettes. If omitted, 
single-sided diskettes are assumed. This is correct for 
all supported handlers 
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The .DRBOT macro puts a pointer to the start of the primary driver into 
location 62 of the handler file. It puts the length (in bytes) of the primary 
driver into location 64. Location 66 of the handler file contains the offset 
from the start of the primary driver to the start of the bootstrap read rou- 
tine. The .DRBOT macro is called before the .DREND macro that you issue. 
The code for the primary driver is placed between the .DRBOT and 
.DREND calls. 

Example: 

Refer to the RT-11 Software Support Manual for an example showing 
the use of .DRBOT. 

2.20 .DRDEF (Device Handler Only) 

The .DRDEF macro sets up handler parameters, calls the driver macros 
from the library, and defines useful symbols. 

Macro Call: .DRDEF name,code,stat,size,csr,vec 

where: 

name is the two-character device name 

code is the numeric code that is the device identifier value for the 
device 

stat is the device status bit pattern. The value for stat may use 
the following symbols: 

FILST* = 100000 SPECL* = 10000 ABTIO* = 1000 
RONLY* = 40000 HNDLR* = 4000 ^ARSZ* = 400 
WONLY$ = 20000 SPFUN* = 2000 

size is the size of the device in 256-word blocks 

csr is the default value for the device's control and status regis- 

ter 

vec is the default value for the device's vector 

The .DRDEF macro performs the following operations: 

1. A .MCALL is done for the following macros: .DRAST; .DRBEG; 
.DRBOT; .DREND; .DRFIN; .DRSET; .DRVTB; .FORK; .QELDF. 

2. If the system generation conditionals TIM$IT, MMG$T, or ERL$G are 
undefined in your program, they are defined as zero. If time-out support 
is selected, the .DRDEF macro does a .MCALL for the .TIMIO and 
.CTIMIO macros. 

3. The .QELDF macro is invoked to define symbolic offsets within a queue 
element. 

4. The symbols listed above are defined for the device status bits. 
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5. The following symbols are defined: 

HDERR*=1 ;HARD ERROR BIT IN THE CSW 

E0F$=20000 ;END of file bit in the CSW 

6. The symbol xxDSIZ is set to the value specified in size. 

7. The symbol xx$COD is set to the specified device identifier code. 

8. The symbol xxSTS is set to the value of the device identifier code plus 
the status bits. 

9. If the symbol xx$CSR is not defined, it is set to the default csr value. 

10. If the symbol xx$VEC is not defined, it is set to the default vector value. 

11. The symbols xx$CSR and xx$VEC are made global. 

You should invoke the .DRDEF macro near the beginning of your handler, 
after all handler specific conditionals are defined. 

Example: 

Refer to the RT-11 Software Support Manual for an example showing 
the use of .DRDEF. 

2.21 .DREND (Device Handler Only) 

The .DREND macro generates the termination table for the termination 
section of the device handler. 

Macro Call: .DREND name 

where: 

name is the two-character device name 

The generation of the termination table, dependent upon certain condi- 
tions, is as follows: 

Label Addresses 

$RLPTR: .WORD ($RELOC) 

$MPPTR: .WORD ($MPPHY) 

$GTBYT: .WORD ($GETBYT) 

$PTBYT: .WORD ($PUTBYT) 

$PTWRD: .WORD ($PUTWRD) 

$ELPTR: .WORD ($ERLOG) 

$TIMIT: .WORD ($TIMIO) 

$INPTR: .WORD ($INTEN) 

$FKPTR: .WORD ($FORK) 

The generation of the labels depends upon the special features chosen dur- 
ing the system generation process. All the pointers in the termination sec- 
tion are initialized when the handler is loaded into memory with the 
.FETCH request. If the device handler is a system device, the pointers are 
initialized at boot time with the addresses shown in the address column. 
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The addresses are located within the monitor. The first five addresses are 
the locations of subroutines in the resident monitor that are available to 
device handlers in an extended memory environment. Device I/O time-out 
service is provided by $TIMIO and error logging is provided by $ERLOG. 
The $INPTR and $FKPTR labels are always filled in by a .FETCH or 
LOAD command. 

Example: 

Refer to the example for .DRAST. 

2.22 .DRFIN (Device Handler Only) 

The .DRFIN macro generates the instructions for the jump back to the 
monitor at the end of the handler I/O completion section. The macro makes 
the pointer to the current queue element a global symbol, and it generates 
position-independent code for the jump to the monitor. When control passes 
to the monitor after the jump, the monitor releases the current queue ele- 
ment. 

Macro Call: .DRFIN name 

where: 

name is the two-character device name 
Example: 

Refer to the example for .DRAST. 

2.23 .DRSET (Device Handler Only) 

The .DRSET macro sets up the option table for the SET command in block 
of the device handler file. The option table consists of a series of four- word 
entries, one entry per option. Use this macro once for each SET option that 
is used. When used a number of times, the macro calls must appear one 
after another. 

Macro Call: .DRSET option, val,rtn[,mode] 

where: 

option is the name of the SET option, such as WIDTH or CR. The 
name can be up to six alphanumeric characters long and 
should not contain any embedded spaces or tabs 

val is a parameter that is passed to the routine in Register R3. 

It can be a numeric constant, such as minimum column 
width, or any one-word instruction that is substituted for an 
existing one in block 1 of the handler. It must not be a zero 

rtn is the name of the routine that modifies the code in block 1 

of the handler. The routine must follow the option table in 
block and must not go above address 776 
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mode is an optional argument to indicate the type of SET parame- 
ter. A NO indicates that a NO prefix is valid for the option. 
NUM indicates that a decimal numeric value is required. 
OCT indicates that an octal numeric value is required. 
Omitting this argument indicates that the option takes nei- 
ther a NO prefix nor a numeric argument 

The .DRSET macro does an .ASECT and sets the location counter to 400 for 
the start of the table. The macro also generates a zero word for the end of 
the table and leaves the location counter there. Thus routines to modify 
codes are placed immediately after the .DRSET calls in the handler, and 
their location in block of the handler file is made certain. 

Example: 

Refer to the RT-11 Software Support Manual for an example of 
.DRSET. 

2.24 .DRVTB (Device Handler Only) 

The .DRVTB macro sets up a table of three- word entries for each vector of a 
multivector device. The table entries contain the vector location, interrupt 
entry point, and processor status word. You must use this macro once for 
each device vector. The .DRVTB macros must be placed consecutively in 
the device handler between the .DRBEG macro and the .DREND macro. 
They must not interfere with the flow of control within the handler. 

Macro Call: .DRVTB name,vec,int[,ps] 
where: 

name is the two-character device name. This argument must be 
blank except for the first-time use of .DRVTB 

vec is the location of the vector, and must be between and 474 

int is the symbolic name of the interrupt handling routine. It 

must appear elsewhere in the handler code. It generally 
takes the form ddINT, where dd represents the two-charac- 
ter device name 

ps is an optional value that specifies the low-order four bits of 

the new Processor Status Word in the interrupt vector. This 
argument defaults to zero if omitted. The priority bits of the 
PSW are set to 7 even if you omit this argument 

Example: 

Refer to the RT-11 Software Support Manual for an example of 
.DRVTB. 

2.25 .DSTATUS 

This .DSTATUS request obtains information about a particular device. 
Macro Call: .DSTATUS retspc,dnam 
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where: 

retspc is the address of a four-word block that stores the status 
information 

dnam is the address of a word containing the Radix-50 device 
name 

.DSTATUS looks for the device specified by dnam and, if successful, returns 
four words of status starting at the address specified by retspc. The four 
words returned are as follows: 

Word 1 Status Word 

Bits 0-7: The low-order byte contains a number that identifies the 
device in the system. The values are currently defined in 
octal as follows: 

= RKOSDisk 

1 = TCll DECtape 

2 = Error Logger 

3 = Line Printer 

4 = Console Terminal or Batch Handler 

5 = RL01/RL02 Disk 

6 = RX02 Diskette 

7 = PC 11 High-speed Paper Tape Reader and 

Punch 

10 = Reserved (V2 PP handler) 

11 = TUlO Magtape 

12 = RFll Disk 

13 = TAll Cassette 

14 = Card Reader (CR11,CM11) 

15 = Reserved 

16 = RJS03/RJS04 Fixed-head Disk 

17 = Reserved 

20 = TJU16 Magtape 

21 = RP02/RP03 Disk 

22 = RXOl Diskette 

23 = RK06/RK07 Disk 

24 = Reserved 

25 = Null Handler 
26-30 = Reserved (DECnet) 

31-33 = Reserved (CTS-300,LQ,LR,LS) 

34 = TU58 DECtape II 

35 = TSll Magtape 

36 = PDT-1 1/130 

37 = PDT-11/150 

40 = Reserved 

41 = Serial Line Printer Handler (LS) 

42 = Message Queue Handler (MQ) 

43 = DRVll^ Interface (MRRT) 

44 = Down-line Load Handler (XT) (MRRT-11 

only) 
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45 = Reserved 

46 = Logical Disk Handler 

47 = KT-11 VM Handler 

50 = MSCP Class Disk Handler 

51 = Single-line Editor 

Bit 8: 1 = Handler can access variable-sized volumes and sup- 

ports .SPFUN 373 
= All volumes used by this device are the same size 

Bit 9: 1 = Enter handler at abort entry whenever program ter- 

minates for any reason 
= Do not enter at abort entry point unless conditions 
for bit 11 are satisfied 

Bit 10: 1 = Handler accepts .SPFUN requests (for example, MT, 

CT, DX) 
= No .SPFUN requests accepted 

Bit 11: 1= Enter handler abort entry every time a job is 

aborted 
= Handler abort entry taken only if there is an active 
queue element belonging to aborted job 

Bit 12: 1= Non RT-11 directory-structured device (magtape, 

cassette) 

Bit 13: 1 = Write-only device (line printer, serial line printer) 

Bit 14: 1 = Read-only device (card reader, paper tape reader) 

Bit 15: 1 = Random-access device (disk, DECtape) 

0= Sequential-access device (line printer, paper tape, 
card reader, magtape, cassette, terminal) 

Word 2 Handler Size 

The size of the device handler in bytes. 

Word 3 Load Address +6 

Non-zero implies the handler is now in memory: zero implies that it 
must be fetched before it can be used. The address returned is the 
load address of the handler + 6. 

Word 4 Device Size 

The size of the device (in 256-word blocks) for block-replaceable de- 
vices; for sequential-access devices, the smallest-sized volume for 
variable-sized devices. The last block on the device is the device size 
-1. 

The device name can be a user-assigned name. .DSTATUS information is 
extracted from the device handler. Therefore, this request requires the han- 
dler for the device to be present on the system device and installed on the 
system. 



2-38 Programmed Request Description and Examples 



Explanation 

Device not found in tables. 



Errors: 

Code 

Example: 



.TITLE DSTflT.MflC 

.DSTATUS - This is an example in the use of the .DSTATUB request. 
The Bxawple uses the "special" mode of CSI to Set an input 
specification from the conscle terminali then uses the .DSTATUS 
request to determine if the output deyioe's handler is loaded! 
if not! a .FETCH request is issued to load the handler into 
memory. Finally a .DELETE request is issued to delete the specified 
file. 





.MCALL 


.DSTATUS,. PRINT. .E 


START: 


.CSISPC 


»OUTSP,»DEFEXT 




.DSTAT 


»STAT.»OUTSP 




TST 


STAT+a 




BNE 


2* 




.FETCH 


•HANLOD -»INSPEC 




BCC 


2* 




.PRINT 


SFEFAIL 




.EXIT 




2t: 


.DELETE 


«AREA,»0(»INSPEC 




BCC 


3* 




.PRINT 


SNQFIL 




BR 


START 


3»: 


.PRINT 
.EXIT 


aFILDEL 


AREA: 


.BLKW 


2 


STAT: 


.BLKW 


4 


DEFEXT: 


.NORD 


,0 ,0 lO 


FEFAIL: 


.ASCIZ 


/?. FETCH Failed?/ 


NOFIL: 


.ASCIZ 


/?File Not Found?/ 


FILDEL: 


.ASCIZ 
.EyEN 


/IFile Deleted!/ 


DUTSP: 


.BLKM 


5*3 


INSPEC: 


.BLKN 


a*E 


HANLOD: 


.BLKW 


1 




.END 


START 



iUse .CSISPC to set output spec 

iChecK on the output deuice 

((CSISPC catches illesal devices!) 

iSee if the deuice is resident 

iBranch if already loaded 

ilt's not loaded. ..brinS it into memory 

iBranoh if successful 

iFetoh failed. ..print error messaSe 

i then e« i t pros ram 

iNow delete the file 

iBranch if successful 

iPrint error messase 

iThen trv asain 

lAcKnoul edse successful deletion 

ithen exit p rosram 

lEMT ArSument blocK 

iBlocK for status 

iNo default extensions 

iFetoh failed messaSe 
iFile not found 
iDelete acKnouil ed Sment 
iFix boundary 

iOutput specs So here 

! Input specs So here 

iHandlers besin loadinS here (if necessary) 
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The .ELAW request eliminates a virtual address window. An implied un- 
mapping of the window occurs when its definition block is eliminated. 

Macro Call: .ELAW area[,addr] 

where: 

area is the address of a two-word EMT argument block 

addr is the address of the window definition block for the window 
to be eliminated 



Programmed Request Description and Examples 2-39 



Request Format: 
RO — > area: 



36 



addr 



Errors: 

Code Explanation 

3 An invalid window identifier was specified. 

Example: 

Refer to the example for the .CRAW request. 



2.27 .ELRG (XM Only) 



The .ELRG request directs the monitor to eliminate a dynamic region in 
physical memory and return it to the free list where it can be used by other 
jobs. 



Macro Call: 
where: 

area 

addr 



.ELRG area [,addr] 



is the address of a two-word EMT argument block 

is the address of the region definition block for the region to 
be eliminated. Windows mapped to this region are unmapped. 
The static region cannot be eliminated 



Request Format: 
RO 



area: 



36 



addr 



Errors: 

Code 

2 
Example: 

Refer to the example for the .CRAW request 



Explanation 

An invalid region identifier was specified. 



2.28 .ENTER 



The .ENTER request allocates space on the specified device and creates a 
tentative entry in the directory for the named file. The channel number 
specified is associated with the file. 

Macro Call: .ENTER area,chan,dblk,len[,seqnum] 

where: 

area is the address of a four-word EMT argument block 

chan is a channel number in the range 0-376(octal) 
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dblk 
len 



seqnum 



is the address of a four-word Radix-50 descriptor of the 
file to be operated upon 

is the file size specification. If the argument is omitted, it 
is not set to in area. An argument of #0 must be speci- 
fied to accomplish this. If an argument is left blank, the 
corresponding location in area is assumed to be set 

The value of this argument determines the file length allo- 
cation as follows: 







either half the largest empty entry or the entire sec- 
ond-largest empty entry, whichever is larger. (A max- 
imum size for nonspecific .ENTER requests can be 
patched in the monitor by changing resident monitor 
offset 314; refer to the example for .PVAL) 



m 



a file of m blocks. The size, 
mum mentioned above 



m, can exceed the maxi- 



-1 the largest empty entry on the device 

is a file number for magtape or cassette. Programming for 
specific devices such as magtape or cassettes is discussed 
in detail in Chapter 10 of the RT-11 Software Support 
Manual. For cassette operation, if this argument is blank, 
a value of is assumed 

For magtape, seqnum describes a file sequence number. 
The action taken depends on whether the file name is 
given or is null. The sequence number can have the follow- 
ing values: 

rewind the magtape and space forward until the file 
name is found or until logical end-of-tape is detected. 
If the file name is found, an error is generated. If the 
file name is not found, then enter file. If the file name 
is a null, a non-file-structured lookup is done (tape is 
rewound) 

n position magtape at file sequence number n if n is 
greater than zero and the file name is not null 

-1 space to the logical end-of-tape and enter file 

-2 rewind the magtape and space forward until the file 
name is found, or until logical end-of-tape is detected. 
The magtape is now positioned correctly. A new logi- 
cal end-of-tape is implied 



Request Format: 



RO 



area: 



2 chan 



dblk 



len 



seqnum 
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On return from this call, RO contains the size of the area actually allocated 
for use. 

The file created with an .ENTER request is not a permanent file until a 
.CLOSE request is given on that channel. Thus, the newly created file is 
not available to .LOOKUP, and the channel cannot be used by .SAVE- 
STATUS requests. However, it is possible to read data that has just been 
written into the file by referencing the appropriate block number. When 
the .CLOSE to the channel is given, any existing permanent unprotected 
file of the same name on the same device is deleted and the new file be- 
comes permanent. Although space is allocated to a file during the .ENTER 
operation, the actual length of the file is determined when .CLOSE is re- 
quested. 

Each job can have up to 255 files open on the system at any time. If re- 
quired, all 255 can be opened for output with the .ENTER function. 

When an .ENTER request is made, the device handler must be in memory. 
Thus, a .FETCH should normally be executed before an .ENTER can be 
done. 

Notes: 

When using the zero-length feature of .ENTER, keep in mind that the 
space allocated is less than the largest empty space. This can have an 
important effect in transferring files between devices (particularly DEC- 
tape and diskette) that have a relatively small capacity. For example, 
transferring a 200-block file to a diskette, on which the largest available 
empty space is 300 blocks, does not work with a zero-length .ENTER. Since 
the .ENTER allocates half the largest space, only 150 blocks are really 
allocated and an output error occurs during the transfer. When transfer- 
ring from A to B, with the length of A unknown, do a .LOOKUP first. This 
request returns the length so that value can be used to do a fixed-length 
.ENTER. The .ENTER request generates hard errors when problems are 
encountered during directory operations. These errors can be detected after 
the operation with the .SERR request. 

Errors: 

Code Explanation 

Channel is in use. 

1 In a fixed-length request, no space greater than or equal to 
m was found; or the device or the directory was found to be 
full. 

3 A file by that name already exists and is protected. A new 

file was not opened. 

Example: 

.TITLE ENTER. MAC 

h 

. ENTER - This is an example in the use of the .ENTER re*iuest. 
The example makes a copy of the file 'TECO.SAV on deuice DK : 
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START: 



1$: 



2t: 



3t: 



5t: 
et: 

7«! 

AREA: 
BLK: 
BUFFRs 
TECOi 



TFILEi 



NOFIL: 

NOENTs 

UERR: 

RERR: 

DONE: 



.MCALL 

.MCALL 

ERRBYT=52 

.LOOKUP 

BCS 

Moy 

.ENTER 

BCS 

CLR 

.READM 

BCC 

TSTB 

BEO 

MOV 

BR 

.WRITW 

INC 

BCC 

MOy 

BR 

.CLOSE 

MOy 

BR 

MDV 

BR 

MOV 

.PRINT 

.EXIT 

.NORD 

.NORD 

.BLKN 

.RAD50 

.RAD50 

.RAD50 

.RAD50 

.RAD50 

.RAD50 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.END 



.LOOKUP (.ENTER ., WRITW .. READW .. CLOSE 
.PRINT ..EXIT 



«AREA.»0>»TECO 

5* 

R0.R3 

• AREA.«1 .«TFILE .R3 
6$ 

BLK 

»AREA .»0 iSBUFFR .»25B. 

2* 

esERRBYT 

3t 

aRERR.RO 

7t 

«AREA 1*1 .»BUFFR .»25B. 

BLK 

1« 

«WERR .RO 

7* 

«1 

• DONE.RO 
7$ 

aNOFIL.RO 
7t 

• NOENT iRO 



0.0.0.0 

25S. 

/DK/ 

/TECO/ 

/SAV/ 

/DK/ 

/OLDTEC/ 

/SAV/ 

/?File not found?/ 

/?. ENTER Failed?/ 

/?Write Error?/ 

/?Read Error?/ 

/TECO Copy Complete/ 

START 



size 



LooKup file TECO. SAV 

Branch if not there! 

Copy size of file to R3 

Enter a neu file of same 

Branch if failed 

Initialize block * to zero 
BLK iRead a block 

Branch if successful 

Was error EOF? 

B ranch if yes 

Hard read error message to RO 

Branch to print uiessasle 
BLK ;Mrite a block 

Buwp block « (doesn't affect C bit) 

Branch if write was ok 

RO => Write error messasre 

Branch to print wessase 

Make new file permanent 

RO => Done message 

Branch to print messaife 

RO => File not found messaSe 

Branch to print it 

RO => Enter Failed message 

Print message on console terminal 

the exit program 

EMT ArSument block 

I/O Buffer 

File descriptors... 



SMessaSe t ext . i 
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The .EXIT request causes the user program to terminate. When used from 
a background job under the FB monitor or XM monitor, or in SJ, .EXIT 
causes KMON to run in the background area. All outstanding mark time 
requests are canceled. Any I/O requests and/or completion routines pending 
for that job are allowed to complete. If part of the background job resides 
where KMON and USR are to be read and SET EXIT SWAP is in effect, the 
user job is written onto the system swap blocks (the file SWAP.SYS). 
KMON and USR are then loaded and control goes to KMON in the back- 
ground area. If SET EXIT NOSWAP is in effect, the user program is simply 
overwritten when a .EXIT is done. If RO = when the .EXIT is done, an 
implicit .HRESET is executed when KMON is entered, disabling the subse- 
quent use of REENTER, START, or CLOSE. 

The .EXIT request allows a user program to pass command lines to KMON 
in the chain information area (locations 500-777octal) for execution after 
the job exits. This is performed under the following conditions: 

1. The word (not byte) location 510 must contain the total number of bytes 
of command lines to be passed to KMON. 
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The command lines are stored beginning at location 512. The lines 
must be .ASCIZ strings with no embedded carriage return or line feed. 
For example: 



.=510 

.WORD B-A 

.ASCIZ /COPY A.MAC B.MAC/ 

.ASCIZ /DELETE A.MAC/ 



3. The user program must set bit 5 or bit 11 in the Job Status Word 
immediately before doing an .EXIT, which must be issued with 
RO = 0. 

When the .EXIT request is used to pass command lines to KMON, the 
following restrictions are in effect: 

1. If bit 11 of the JSW is set and if the feature is used by a program that is 
invoked through an indirect file, the indirect file context is aborted 
before executing the supplied command lines. Any unexecuted lines in 
the indirect file are never executed. 

2. If bit 5 of the JSW is set and the feature is used by a program invoked 
through an indirect file, the indirect file context is preserved across the 
.EXIT request. 

3. An indirect file can be invoked, using the steps described above, only 
if a single line containing the indirect file specification is passed to 
KMON. Attempts to pass multiple indirect files or combinations of indi- 
rect command files and other KMON commands yield incorrect results. 
An indirect file must be the last item on a KMON command line. 

The .EXIT request also resets any .CDFN and .QSET calls that were done 
and executes an .UNLOCK if a .LOCK has been done. Thus, the CLOSE 
command from the keyboard monitor does not operate for programs that 
perform .CDFN requests. 

An attempt to use a .EXIT from a completion routine aborts the running 
job. 

NOTE 

You must make sure that the data being passed to KMON is 
not destroyed during the .EXIT request. Extreme care should 
be exercised so that the user stack does not overwrite this 
data area. If the user passes command lines to KMON, the 
stack pointer should be reset to lOOO(octal) or above before 
an exit is made. 

Macro Call: .EXIT 
Errors: 

None. 
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Example: 



.TITLE EXIT. MAC 



i + 



i .EXIT - This is an example in the use of the .EXIT re-iuest. 
i The example demonstrates how a oomwand line way be passed to 
i Keyboard Monitor after Job execution is stopped. 





.MCALL 


• EXIT 


CHNIFt 


= aooo 




JSkl 


= aa 




START! 


MOM 


»510iR0 




MOV 


•CMDSTR.Rl 




MOV 


wSTflRT.SP 


10«: 


MOVB 


(Rl)+ ,(R0)+ 




CMP 


Rl ,«CMDEND 




BLO 


10* 




BIS 


«CHNIF*.li«JSW 




CLR 


RO 




.EXIT 




CMDSTRs 


.UORD 


CMDEND-CMDSTR 




.ASCIZ 


"DIRECT/FULL 


CMDEND: 


.EVEN 






.END 


START 



«.MAC" 



iChain bit in JSM 

iJSW location 

iRO => Communication area 

iRl => Command strinS 

iMaKe sure that the staoK is 

inot in the communication area... 

iCopy command strini 

iOone? 

iBranoh if not 

iSet the "chain" bit to alert KMON that 

ithere's a command in the communication area 

iRO must be zero ! 

(Exit the pro 91 ram 



2.30 .FETCH/.RELEAS 



The .FETCH request loads device handlers into memory from the system 
device. 

Macro Call: .FETCH addr,dnam 

where: 

addr is the address where the device handler is to be loaded 

dnam is the pointer to the Radix-50 device name 

The storage address for the device handler is passed on the stack. When the 
.FETCH is complete, RO points to the first available location above the 
handler. If the handler is already in memory, RO contains the same value 
that was initially specified in the argument addr. If the argument on the 
stack is less than 400(octal), it is assumed that a handler .RELEAS is being 
done. (.RELEAS does not dismiss a handler that was loaded from the 
KMON; an UNLOAD must be done.) After a .RELEAS, a .FETCH must be 
issued in order to use the device again. 

Several requests require a device handler to be in memory for successful 
operation. These include: 



.CLOSE 
.LOOKUP 
.ENTER 
.RENAME 



.READC 
.WRITC 
.READW 
.WRITW 



.READ 
.WRITE 
.SPFUN 
.DELETE 



.SFDAT 
.FPROT 
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When running under the foreground/background monitor, handlers for the 
foreground program or a system job must be loaded with the LOAD com- 
mand before execution. 

NOTE 

I/O operations cannot be executed on devices unless the han- 
dler for that device is in memory. 



Errors: 

Code 


Example: 



Explanation 

The device name specified is not installed in the system, or 
there is no handler for that device in the system. 



.TITLE FETCH. MAC 

.FETCH - This is an example in the use of the .FETCH request. 
The example uses the "special" mode of CSI to set an input 
specification from the console terminal) then uses the .DSTATUS 
request to determine if the output deuioe's handler is loaded! 
if not I a .FETCH request is issued to load the handler into 
memory. Finally a .DELETE resuest is issued to delete the specified 
file. 



. MCftLL 



.DSTftTUS .. PRINT .. EXIT . .FETCH , . CSISPC . .DELETE 



START: 


.CSISPC 


•OUTSP .«DEFEXT 




.DSTAT 


«STAT.»DUTSP 




TST 


STAT+4 




BNE 


2* 




.FETCH 


•HANLOD. "INSPEC 




BCC 


2« 




.PRINT 


•FEFAIL 




.EXIT 




2$: 


.DELETE 


«AREA.«0 , "INSPEC 




BCC 


3* 




.PRINT 


•NOFIL 




BR 


START 


3*: 


.PRINT 
.EXIT 


•FILDEL 


AREA: 


.BLKW 


2 


STAT: 


.BLKM 


a 


DEFEXT: 


.MDRD 


lO ,0 lO 


FEFAIL: 


.ASCIZ 


/?. FETCH Failed?/ 


NOFIL! 


.ASCIZ 


/?File Not Found?/ 


FILDEL: 


.ASCIZ 
.EVEN 


/IFile Deleted!/ 


OUTSP: 


= .BLKW 


5*3 


INSPEC: 


= .BLKW 


a*B 


HANLODi 


= .BLKW 


1 




.END 


START 



iUse .CSISPC to 9et output spec 

iChecK on the output device 

ifCSISPC catches illesal deuices!) 

iSee if the deuioe is resident 

iBranch if already loaded 

ill's not 1 oaded . . . b Tins it into memory 

iBranch if successful 

iFetch failed. ..print error messaSe 

ithen exit pros ram 

iNou delete the file 

iBranch if successful 

iPrint error messaSe 

iThen t ry asain 

iAcKnouledse successful deletion 

ithen exit proSram 

SENT Argument block 

iBlooK for status 

iNo default extensions 

SFetch failed messaSe 
iFile rot found 
iDelete acKnouil ed smen t 
iFix boundary 

iOutPut specs So here 

i Input specs sfo here 

iHandlers beain loading here (if necessary) 



The .RELEAS request notifies the monitor that a fetched device handler is 
no longer needed. The .RELEAS is ignored if the handler is (1) the system 
device, (2) not currently resident, (3) resident because of a LOAD command 
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to the keyboard monitor. .RELEAS from the foreground or system job under 
the FB monitor or the XM monitor is always ignored, since the foreground 
job in a FB environment or extended memory environment can only use 
handlers that have been loaded by the DOAD command. 

Macro Call: .RELEAS dnam 

where: 

dnam is the address of the Radix-50 device name 
Errors: 

Code Explanation 

Device name is invalid. 
Example: 

.TITLE RELEAS. MAC 

iln this examplet the DECtape handler (DT) is loaded into memoryi 
iusedi then released. If the system device is DECtape > the handler is 
ialwavs resident! and .FETCH will return HSPACE in RO. 

. MCALL . FETCH » . RELEAS . . EXI T . . PR I NT 

START: .FETCH »HSPACE .«DTNAME iLoad DT handler 
BCS FERR iNot auailatle 



i Use h 


andler 




.RELEA: 




BR 


FERR: 


.PRINT 


DTNAME: 


.RAD50 


NODT; 


.ASCIZ 




.EVEN 


HSPACE: 





•DTNAME iMark DT no lonSer in 

i m e m r y 
START 

»NODT )DT not available 

/DT / iName for DT handler 

/?DT HANDLER NOT AVAILABLE/ 

iBeSinnins of handler 
ia rea 



.END 



START 



2.31 .FORK (Device Handler and Interrupt Service Routine Only) 

The .FORK call is used when access to a shared resource must be serialized 
or when a lengthy but non-time-critical section of code must be executed. 
.FORK issues a subroutine call to the monitor and does not use an EMT 
instruction request. 

Macro Call: .FORK fkblk 



where: 



fkblk is a four- word block of memory allocated within the driver 



Errors: 



None. 
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The .FORK macro expands as follows: 

.FORK fkblK 
JSR Z5j§*FKPTR 
.WORD fkblk-. 

The .FORK call must be preceded by an .INTEN call, and the address of a 
four-word block must be supplied with the request. Your program must not 
have left any information on the stack between the .INTEN and the .FORK 
call. The contents of registers R4 and R5 are preserved through the call, 
and on return registers RO through R3 are available for use. 

If you are using a .FORK call from a device handler, it is assumed that you 
are also using the other macros (.QELDF, .DRBEG, .DRAST, .DRFIN, and 
.DREND) provided for handlers. 

The .DREND macro allocates a word for $FKPTR. This word is filled in at 
bootstrap time for a system device or at LOAD or .FETCH time for a non- 
system device. 

If you want to use the .FORK macro in an in-line interrupt service routine 
rather than in a device handler, you must set up $FKPTR. The recom- 
mended way to do this is as follows: 

iAddress containins base 
iaddress of RMON 
iMoriitor offset con tain ins 
loffset to fork processor 
iReturn offset in RO 
iAdd RMON base address 
iSawe as address of the 
!fork processor 



AREA: .BLKW 2 
*FKPTR: .WORD 

Once the pointer is set up, use the macro in the usual way as follows: 

.FORK fkblk 

This method permits you to preserve both R4 and R5 across the fork. 

The .FORK request is linked into a queue and serviced on a first-in first- 
out basis. On return to the driver or interrupt service routine following the 
call, the interrupt has been dismissed and the processor is executing at 
priority 0. Therefore, the .FORK request must not be used where it can be 
reentered using the same fork block by another interrupt. It also should not 
be used with devices that have continuous interrupts that cannot be dis- 
abled. The RT-11 Software Support Manual gives additional information 
on the .FORK request. 

Notes: 

For use within a user interrupt service routine, monitor fixed offset 402 
(FORK) contains the offset from the start of the resident monitor to the 
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SYBPTR=54 




F0RK=402 




.GMAL 


»AREA, «FORK 


ADD 


mtSYSPTR. RO 


MOyE 


RO. $FKPTR 



.FORK request processor. A .FORK can be done by computing the address 
of the .FORK request processor and using a subroutine instruction. (Under 
the XM monitor, only privileged jobs can contain user interrupt service 
routines.) For example: 





SYSPTR 


= 54 






F0RK=402 






.GVAL 




• AREA. «tFORK 




ADD 




esBYSPTRt RO 




MOy 




RO. Ra 




JSR 




R5. (R4) 




.MORD 




BLOCK-. 


AREA: 


* 

.BLKU 


2 




BLOCK: 


.BLKW 


i\ 





lAd dress containing base 
iaddress of RMON 
iMonitor offset oontainins 
ioffset to forK processor 
iReturn offset in RO 
;Add RMON base address 

iCall fbrK process 



This method destroys the contents of R4. 
Example: 

Refer to the example following the description of .DRAST. 



2.32 .FPROT 



The .FPROT programmed request sets or removes file protection on indi- 
vidual RT-11 files. A file marked as protected cannot be deleted by 
.CLOSE, .DELETE, .ENTER, or .RENAME requests. However, the con- 
tents of a protected file are not protected against modification. For example, 
a .LOOKUP of a protected file followed by a .WRITE to the file is per- 
mitted. 

Protection is enabled by setting bit 15 of a file's directory entry status word. 

Macro Call: .FPROT area, chan, dblk, prot 



where: 



area 
chan 
dblk 

prot 



is the address of a four-word EMT argument block 

is a channel number in the range 0-376(octal) 

is the address of a four-word block containing the filespec in 
Radix-50 of the file 



= #1 — to protect the file from deletion 

= #0 — to remove protection so that the file can be deleted 

Request Format: 
RO area 



43 chan 



dblk 



prot 
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Errors: 



Code Explanation 

Channel in use 

1 File not found 

2 Invalid operation 

3 Invalid value for PROT 



Example: 



;.FPROT> .SFDAT exawple. 

iThi5 is an example of the use of the .FPROT and .SFDAT 

iprosrawwed requests. It uses the "special" mode of the CBI to 

iset an input filespec from the console terminal. .DSTATUS is 

iused to determine if the deuice handler is loaded. If not. a 

i. FETCH request is used to load the handler into memory. FinaUyi 

ithe file is marked as protected usins the .FPROT request and 

ithe file date is chansed to the current system date uslns the 

!. SFDAT request. 

1 

.MCALL .FPRDT. .FETCH, .CBISPCi .DSTATUS. .SFDAT, .PRINT. .EXIT 



START: 



1«: 



Z«: 



10$: 

EMTBLK: 

DEFEXT: 

STAT: 

LDFAIL: 

PRFAIL: 

SQFAIL: 

DUTSP: 

INSPEC: 

HANLOD: 



.CSISPC 

.DSTAT 

TST 

BNE 

.FETCH 

BCC 

.PRINT 

BR 

.FPRDT 

BCC 

.PRINT 

BR 

.SFDAT 

BCC 
•PRINT 
BR 
.EXIT 

.BLKW 

.MORD 

.BLKM 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.EI.IEN 

.BLKM 

.BLKM 

.BLKU 

.END 



•OUTSP, •DEFEXT 

• STAT ."INSPEC 
STAT+a 

It 

•INSPEC 

1« 

•LDFAIL 

START 

•EMTBLK, «0, •INSPEC. 

Z* 

•PRFAIL 

START 

• EMTBLK 1 •0, •INSPEC, 

lOt 

•SDFAIL 

START 



iUse CSI to set input filespec 

iCheoK the device 

ito see if the hanndler is resident 

iBranoh if it is 

iOtherwise, load that handler 

ioK 

lOtheruise, print load error messasre 

i and try a^fain 

•1 iMark file as protected 

iand branch if oKay 

lOtheruiisei print protect error message 

iand try asain 

•0 iFlnally, set current date 

iA date of means "use current system date" 

iBranch if euerythinS is oKay 

iOtheruise, print date error messaie 

iand try asain 

iEuerythins okay - exit to KMON 



'I iThe EMT araiument block is built here 

0,0,0,0 iNo default extensions 

a iBlocK for .DSTATUS to use 

/Error in .LOAD request/ 

/Error in .FPROT request/ 

/Error in .SFDAT request/ 

5*3 iOutPut specs <a here 

fl*B ilnput specs So here 

1 {Handlers besin loading here (if necessary) 

START 



2.33 .GMCX (XM Only) 



The .GMCX request returns the mapping status of a specified window. 
Status is returned in the window definition block and can be used in a 
subsequent mapping operation. Since the .CRAW request permits combined 
window creation and mapping operations, entire windows can be changed 
by modifying certain fields of the window definition block. 

The .GMCX request modifies the following fields of the window definition 
block: 
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W.NAPR base page address register of the window 

W.NBAS window virtual address 

W.NSIZ window size in 32-word blocks 

W.RID region identifier 

If the window whose status is requested is mapped to a region, the .GMCX 
request loads the following additional fields in the window definition block: 

W.NOFF offset value into the region 

W.NLEN length of the mapped window 

W.NSTS state of the WS.MAP bit is set to 1 in the window status 
word 

Otherwise, these locations are zeroed. 

Macro Call: .GMCX area[,addr] 

where: 

area is the address of a two-word EMT argument block 

addr is the address of the window definition block where the speci- 
fied window's status is returned 

Request Format: 

RO — > area: 



36 6 



addr 



Errors: 

Code Explanation 

3 An illegal window identifier was specified. 
Example: 

Refer to the example for the .CRAW request. 



2.34 .GTIM 



.GTIM allows user programs to access the current time of day. The time is 
returned in two words and given in terms of clock ticks past midnight. 

Macro Call: .GTIM area,addr 

where: 

area is the address of a two-word EMT argument block 

addr is the address of the two-word area where the time is to be 
returned 

Request Format: 

RO —> area: 



21 



addr 
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The high-order time is returned in the first word, the low-order time in the 
second word. Your program must perform the conversion from clock ticks to 
hours, minutes, and seconds. 

The basic clock frequency (50 or 60 Hz) can be determined from the configu- 
ration word in the monitor (offset 300 relative to the start of the resident 
monitor). In the FB monitor, the time of day is automatically reset after 
24:00, when a .GTIM request is done and the date is changed if necessary. 
In the SJ monitor, the time of day is not reset unless SJ timer support was 
selected during the system generation process. The month is not automati- 
cally updated in either monitor. (Proper month and year rollover is a spe- 
cial feature that you enable through the system generation process.) 

The default clock rate is 60 cycles, that is, 60 ticks per second. Consult the 
RT—11 System Generation Guide if conversion to a 50-cycle rate is neces- 
sary. 

Because day rollover is done only through a .GTIM request, make sure that 
your program receives the correct time and day by issuing a .GTIM request 
before using the .DATE request. Nearly all RT-11 system utility programs 
issue a .GTIM request to make sure that rollover occurs daily. If you do not 
use a system utility program regularly, issue a .GTIM request at least once 
during a 24-hour period. 

NOTE 

There are also several SYSLIB routines that perform time 
conversion (see Chapter 3). They are CVTTIM, TIMASC, 
TIME, and SECNDS. 

Errors: 

None. 
Example: 

.TITLE GTIM. MAC 



.GTIM - This is an example in the use of the .GTIM request. 
This example is a subroutine that can be assembled separately 
and linked with a user program. 

CALLING SEQUENCE: CALL TIME 



INPUT! 
OUTPUT; 



rone 

RA = Minutes in hi byte / hours in lo byte 

R5 = TicKs in hi byte / seconds in lo byte 

(in that order for ease of remoual !) 



ERRORS: none possible 

NOTE: This example calls SYSLIB functions '$DiyTK' t, '$DiyBO' 





.GLOBL 


$DiuTK i*Diyeo 




.MCALL 


.GTIM 


TIME: : 


MOU 


STICKS. Rl 




.GTIM 


«AREA iRl 



iRl points to uhere to put time 
iGet ticks since midrisht via .GTIM 
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Moy 


(R1>+.R0 






Moy 


SRI >R1 






CALL 


»OIUTK 






MDM 


R3iR5 






SWAB 


R5 






CALL 


SOIMGO 






BISB 


R3.R5 






CALL 


«DIUBO 






MOV 


R3>Ra 






SMAB 


Rfl 






BISB 


Rl iR4 






RETURN 






AREA: 


.BLKM 


Z 




TICKS! 


.WORD 
.END 


0.0 


2.35 


.GTJB 







iRO ■ lo order time 

iRl = hi order time 

ICall SYSLIB 32 bit divide by olK frt^ 

tSave ticKs 

iPut them in hi byte 

ICall SYSLIB divide by 60. routine 

)Put seconds in lo byte 

{Divide by 60. once aiain 

(Put Minutes in R4 

iMove them to hi byte 

iPut hours in lo byte 

Sand return 

lEMT argument area 

ITioKs since midnisht returned here 



The .GTJB request returns information about a job in the system. 

Macro Call: .GTJB area,addr[,jobblk] 

where: 

area is the address of a three-word EMT argument block 

addr is the address of an eight-word or twelve-word block into 
which the parameters are passed. The values returned are: 

Word 1 Job Number = priority level *2 (background job 
is 0; system jobs are 2, 4, 6, 10, 12, 14; and fore- 
ground job is 16 in system job monitors; back- 
ground job is and foreground job is 2 in FB and 
XM monitors; job number is in a SJ monitor) 

2 High-memory limit of job partition (highest loca- 
tion available to a job in low memory if the job 
executes a privileged .SETTOP #-2 request) 

3 Low-memory limit of job partition (first location) 

4 Pointer to I/O channel space 

5 Address of job's impure area in FB and XM moni- 
tors 

6 Low byte: unit number of job's console terminal 
(used only with multiterminal option; when 
multiterminal feature is not used) 

High byte: reserved for future use 

7 Virtual high limit for a job created with the 
linker /V option (XM only; when not running 
under the XM monitor or iffV option is not used) 

8-9 Reserved for future use 
10-12 ASCII logical job name (system job monitors 
only; contains zeroes for non-system jobs in FB 
and XM, not defined in SJ) 

jobblk is a pointer to a three-word ASCII logical job name for 
which data is being requested 
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Word 4 of addr, which describes where the I/O channel words begin, nor- 
mally indicates an address within the job's impure area. However, when a 
.CDFN is executed, the start of the I/O channel area changes to the user- 
specified area. 

l^thejobblk argument to the .GTJB request is between and 16 when the 
status of a job is requested, it is interpreted as a job number, lithejobblk 
argument is 'ME', or equals -1, information about the current job is re- 
turned, lithe jobblk argument is omitted, or equals -3 (a V03B-compatible 
parameter block), only eight words of information (corresponding to words 
1-8 of addr) are returned. 

In an F/B environment without the system job feature, you can get another 
job's status only by specifying its job number (0 or 2). 

Request Format: 

RO 



area: 



20 







addr 



jobblk 



Errors: 

Code Explanation 

No such job currently running. 
Example: 

See the program GTJB. MAC in the example listing. 

.TITLE GTJB. MAC 



.GTJB - This is an example of the .GTJB request. The 
example issues the request to determine if there is a loaded 
Foreground Job in the system. This proiram will execute properly 
with either a normal FB monitor or an FB monitor that includes 
System Job support. 



START; 



1$: 



2*! 



LIST! 



.MCALL 


.GVALf . 


GTJB, .PR 


SYSGEN= 


372 




SYSJOB= 


40000 




MOy 


*2, 


Rl 


.GVAL 


•LIST. 


•SYSGEN 


BIT 


•BYSJDB 


. RO 


BEQ 


1* 




nog 


»16> 


Rl 


.GTJB 


•LIST. 


•JOBARG. 


BCS 


2$ 




.PRINT 


•FGLOAD 




.EXIT 






.PRINT 


• NOFG 




.EXIT 







. .EXIT 



Rl 



.BLKW 



iFixed offset to SYSGEN uiord 
iSystem Job option bit 

>Assu,»,e FG Job number = 2 

iGet SYSGEN option word 

iSystem Job monitor? 

iB ranch if not 

!If 50. FG Job number = IB 

iFind out if FG loaded 

iBranch if no aotiue FG Job 

.Announce that FG Job is loaded 

iand exit from prosram. 

.Announce that there's no FG Job 

iand exit from proSram. 

iEMT ArSument block 
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JOBARG: 
FGLOAD: 



.BLKW 



12. 



.ASCIZ /!FG LoadBd!/ 
NOFG: .ASCIZ /?No FG Job?/ 



iJob parameters passed bacK here 

iFG loaded messase 
iNo FG messaale 



.END 



START 



2.36 .GTLIN 



The .GTLIN request collects a line of input from either the console terminal 
or an indirect command file, if one is active. This request is similar to 
.CSIGEN and .CSISPC in that it requires the USR, but no format checking 
is done on the input line. Because the .GTLIN command is implemented in 
the USR, the CSI will generate an error message if you attempt to input 
more than 80 characters to a .GTLIN request. Normally, .GTLIN collects a 
line of input from the console terminal and returns it in the buffer specified 
by you. However, if there is an indirect command file active, .GTLIN col- 
lects the line of input from the indirect command file just as though it were 
coming from the terminal. 

When bit 3 of the Job Status Word is set and your program encounters a 
CTRL/C in an indirect command file, the .GTLIN request collects subse- 
quent lines from the terminal. Note that if you then clear bit 3 of the Job 
Status Word, the next line collected by the .GTLIN request is the CTRL/C 
in the indirect command file; this causes the program to abort. Further 
input will come from the indirect command file, if there are any more lines 
in it. When bit 14 of the Job Status Word is set, the .GTLIN request passes 
lowercase letters. 

An optional prompt string argument (similar to the CSI asterisk) allows 
your program to query for input at the terminal. The prompt string argu- 
ment is an ASCIZ character string in the same format as that used by the 
.PRINT request. If input is from an indirect command file and the SET TT 
QUIET option is in effect, this prompt is suppressed. If SET TT QUIET is 
not in effect, the prompt is printed before the line is collected, regardless of 
whether the input comes from the terminal or an indirect file. The prompt 
appears only once. It is not reissued if an input line is canceled from the 
terminal by CTRL/U or multiple DELETE characters, unless the single- 
line editor is running. 

If your program requires a nonstandard command format, such as the user 
identification code (UIC) specification for FILEX, you can use the .GTLIN 
request to accept the command string input line. .GTLIN tracks indirect 
command files and your program can do a pre-pass of the input line to 
remove the nonstandard syntax before passing the edited line to .CSIGEN 
or .CSISPC. 

NOTE 

In an F/B environment, .GTLIN performs a temporary im- 
plicit unlock while the line is being read from the console. 

Macro Call: .GTLIN linbufl,prompt][,type] 
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where: 



linbuf is the address of the buffer to receive the input line. This 
area must be at least 81 bytes in length. The input line is 
stored in this area and is terminated with a zero byte 

prompt is an optional argument and is the address of a prompt 
string to be printed on the console terminal. The prompt 
string has the same format as the argument of a .PRINT 
request. Usually, the prompt string ends with an octal 200 
byte to suppress printing the carriage return/line feed at 
the end of the prompt 

type is an optional argument which forces .GTLIN to take its 

input from the terminal rather than from an indirect file 

NOTE 

The only requests that can take their input from an indirect 
command file are .CSIGEN, .CSISPC, and .GTLIN. The 
.TTYIN and .TTINR requests cannot get characters from an 
indirect command file. They get their input from the console 
terminal (or from a BATCH file if BATCH is running). The 
.TTYIN and .TTINR requests and the .GTLIN request with 
the optional type argument are useful for information that is 
dynamic in nature — for example, when all files with a .MAC 
file type need to be deleted or when a disk needs to be initial- 
ized. In these circumstances, the response to a system query 
should be collected through a .TTYIN or a .GTLIN with the 
type argument so that confirmation can be done interactively, 
even though the process may have been invoked through an 
indirect command file. However, the response to the linker's 
Transfer Symbol? query would normally be collected through 
a .GTLIN, so that the LINK command could be invoked and 
the start address specified from an indirect file. Also, if there 
is no active indirect command file, .GTLIN simply collects an 
input line from the console terminal by using .TTYIN re- 
quests. 



Errors: 

None. 
Example: 



.TITLE GTLIN. MAC 



.GTLIN - This is an example in the use of the .GTLIN request. 
The example merely accepts input from the console terminal and 
echoes it bacK. 
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.MCflLL 



• GTLIN.. PRINT. .EXIT 



START: 



1«: 

BUFF: 

PROMT: 



.GTLIN 

TSTB 

BEQ 

.PRINT 

CLRB 

BR 

.EXIT 

.BLKM 

.ASCII 

.END 



•BUFF. "PROMT 

BUFF 

1$ 

«BUFF 

BUFF 

START 

ai. 



.Get a line of input from Keyboard 

iNothinS entered? 

iBranch if nothinsr entered 

iEoho the input bacK 

iClear first char of buffer 

iGa bacK for more 

iExit prosram on null input 

iSO character buffer (ASCIZ for .PRINT) 



/Enter some t hin«>/<200> 
START 



2.37 .GVAL/.PVAL 



The .GVAL request returns in RO the contents of a monitor fixed offset; the 
.PVAL request changes the contents of a monitor offset. The .PVAL request 
also returns the old contents of an offset in RO to simplify saving and 
restoring an offset value. .GVAL and .PVAL must be used in an XM envi- 
ronment to read or change any fixed offset, and should be used with other 
RT-11 monitors for compatibility with XM and possible future releases of 
RT-11. 

Chapter 3 of the RT-11 Software Support Manual contains a table of the 
monitor's fixed offset locations. 

Macro Calls: .GVAL area, offset 

.PVAL area, offset, value 

where: 

area is the address of a two- or three-word EMT argument block 

offset is the displacement from the beginning of the resident moni- 
tor to the word to be returned in RO 

value is the new value to be placed in the fixed offset location 

Request Format for .GVAL: 

RO -> area: 



34 







offset 



Request format for .PVAL 
RO -^ area: 



34 



offset 



value 



Errors: 



Code Explanation 

The offset requested is beyond the limits of the resident mon- 
itor. 
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Example: 



.TITLE 



.GVftL.MAC 



.GyAL - This is an example of the .GUAL request. It finds out 
if the foresround Job is active. Compare this example with the 
.GTJB example. 



.MCALL .GVALi 



.PRINT. 



.EXIT 





CONFIG= 


300 ;Offset 




FJGBt= 


200 iBit in 


START: 


.Gi.)AL 


•AREAt «CaNFIG 




BIT 


•FJOB$,RO 




BEO 


1$ 




.PRINT 


•FGACT 




.EXIT 




It: 


.PRINT 
.EXIT 


»NOFG 


AREA: 


.BLKU 


2 


FGACT: 


.ASCIZ 


/ ! FG is active 


NOFG: 


.ASCIZ 
.EVEN 


/? No FG Job ?/ 



iOffset in monitor of con f i su rat i on word 
oonfii word is on if FG active 



iGet monitor CONFIG word in RO 
iSee if FG Active bit is on 
iB ranch if not 
iAnnounce FG is active 
ithen exit pros ram 
lAnnounoe there's no FG Job 
ithen exit pro sram 

iEMT arsument blooK 
!/ iFG active message 
!No FG message 



.END 



START 



.TITLE 



. PVAL.MAC 



i .PVAL - This is an example of the .PVAL resuest. The example 

i illustrates a way of ohansins the default file size created 

! by the .ENTER request. Compare this example with the .PEEK/. POKE 

i example. . pyAL is used both to chanse the default file size and 

i to read the old default file size, returning the old value in RO. 



START: 



.nCALL 

MAXBLK= 

.PIJAL 

MOV 

.EXIT 



.PWAL. 
3ia 



.EXIT 



iMonitor offset of default file size 



EMTBLK; 


.BLKW 


3 


NEUSIZ: 


.MORD 


100. 


DLDSIZ: 


.UORD 






.END 



"EMTBLK ."MAXBLK .SNEWSIZ iChanSe default file size to 100. blocks 

RO . OLDSIZ iSave the old default 

iWe'll Just exit now i but presumably 
!in a real prosram we'd do more 
iprocessins. perhaps creatini files 
iwith the new default size we Just 
iset. then before exitins we'd restore 
ithe old default size. 

iEMT argument blocK 

iOld default size is saved here 
START 



2.38 .HERR/.SERR 



.HERR and .SERR are complementary requests used to govern monitor 
behavior for serious error conditions. During program execution, certain 
error conditions can arise that cause the executing program to be aborted 
(see Table 2-2). 

Normally, these errors cause program termination with one of the ?MON- 
F-error messages. However, in certain cases it is not feasible to abort the 
program because of these errors. For example, a multi-user program must 
be able to retain control and merely abort the user who generated the error. 
.SERR accomplishes this by inhibiting the monitor from aborting the job 
and causing an error return to the offending EMT. On return from that 
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request, the carry bit is set and byte 52 contains a negative value indicat- 
ing the error condition that occurred. In some cases (such as the .LOOKUP 
and .ENTER requests), the .SERR request leaves channels open. It is your 
responsibility to perforin .PURGE or .CLOSE requests for these channels, 
otherwise subsequent .LOOKUP/.ENTER requests will fail. 

.HERR turns off user error interception. It allows the system to abort the 
job on fatal errors and generate an error message. (.HERR is the default 
case.) 

Macro Calls: .HERR 
.SERR 

Request Formats: 

.HERR Request RO = 
.SERR Request RO = 

Errors: 

Table 2-2 contains a list of the errors that are returned if soft error 
recovery is in effect. Traps to locations 4 and 10, floating-point excep- 
tion traps, and CTRL/C aborts are not inhibited. These errors have 
their own recovery mechanism. 

Table 2-2: Soft Error Codes (.SERR) 

Code Explanation 



5 





4 






-1 Called USE from completion routine. 

-2 No device handler; this operation needs one. 

-3 Error doing directory I/O. 

-4 .FETCH error. Either an I/O error occurred while the handler was being used, or 
an attempt was made to load the handler over USR or RMON. 

-5 Error reading an overlay. 

-6 No more room for files in the directory. 

-7 Invalid address (FB only); tried to perform a monitor operation outside the job 
partition. 

-10 Invalid channel number; number is greater than actual number of channels that 
exist. 

-11 Invalid EMT; an invalid function code has been decoded. 

-12 Reserved for monitor internal use. 

-13 Reserved for monitor internal use. 

-14 Invalid directory. 

-15 Unloaded XM handler. 

-16 Reserved for monitor internal use. 

-17 Reserved for monitor internal use. 

-20 Reserved for monitor internal use. 

-21 Reserved for monitor internal use. 

-22 Reserved for monitor internal use. 
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Example: 



.TITLE HERR.MflC 
I- 
.HERR / .SERR - This 15 an exauiple in the use of the .HERR & .SERR 
requests. Ncrmallr fatal errors uill cause a return to the user 
proaram for processins and printing of an appropriate error messajei 



.MCflLL 
.MCALL 



.HERR I 
.EXIT I 



,SERR ..LOOKUP. .PURGE 
, PRINT. .CSISPC 



START: 



ERROR: 



FTLERR: 



.SERR 

.CSISPC 

.PURGE 

.LOOKUP 

BCS 

.HERR 

.PRINT 

.EXIT 

MOWB 

BMI 

.PRINT 

BR 

NEG 

DEC 

flSL 

MOV 

.PRINT 

BR 



• OUTSP.ttDEFEXT 
«0 

• AREA ,»0 .«0UTSP + 3G 
ERROR 

■LUPOK 

e«52 iRO 

FTLERR 

sNOFIL 

START 

RO 

RO 

RO 

TBL(RO) .RO 

START 



iLet proaraw handle fatal errors 
iUse .CSISPC to Set filespeo 



iBranch if there uias an error 
iNow permit '?MON~F-' errors, 
iflnnounoe successful LOOKUP 
iEk i t pros raw 
iwas the error fatal? 
iBranch if yes 

iT ry aSain . . ■ 

iMaKe error * positiue 

I Ad Just by one 

iMultiply by 2 to maKe an index 

iPut messase address into RO 

land print it. 

iGo try some more errors 



TBL: 



MZ: 

M3; 

M7: 

MIO: 

Mil: 

M12; 

M13: 

M14: 

M17: 

Ml: 

Mfl: 

M5: 

M6: 

M15: 

MIS: 

MZO: 

M2i: 

MZZ: 

NOFIL: 



Ml 
Ml 
MZ 
M3 

na 

M5 

MS 

M7 

MIO 

Mil 

MIZ 

M13 

Mia 

M15 

M16 

M17 

MZO 

MZl 

MZZ 

.ASCIZ 
.ASCIZ 
.ASCIZ 
.ASCIZ 
.ASCIZ 
.ASCIZ 
.ASCIZ 
.ASCIZ 
.ASCIZ 



iTable of Error Messase Addresses 



/?Inualid DeMicE 
/?Oirectory I-O Error?/ 
/?Addre55 CheoK Error?/ 
/?Inualid Channel?/ 
/?Inoalid EMT?/ 
/?Trap to a?/ 
/?Trap to 10?/ 
/?Inualid directory?/ 
/?Memo ry e r ro r?/ 



SEr ro r Messases . . . 
-or- No Handler?/ 



.ASCIZ 
.ASCIZ 



/?Not Possible?/ 
/?File Not Found?/ 



iNot 
iNot 
iNot 
iNot 
iNot 
iNot 
iNot 
iNot 
iNot 



possible 
possible 



possible in this 



possible 
possible 
possible 
possible 
possible 
possible 



this 
this 



in 



this 
this 
this 
this 
this 
this 



p rosram 
p rosram 
p roSram 
p roSram 
p ro S ram 
p rosram 
p roSraw 
p rosram 
p rosram 
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LUPOK: 


.flSCIZ 
.EVEN 


/Lookup 


succeeded/ 


iFix boundary 




AREA: 


.BLKW 


a 




iEMT Arsument blocK 




DEFEXT: 


.WORD 


0,0,0.0 




iNo default extensions 




OUTSP; 


.BLKW 


5*3 




iOutPut specs io here 




INBPEC: 


.BLKW 


a«B 




ilnput specs 90 here 




HANLDD: 


.BLKW 


1 




■ Handlers be^in loadins here 


(if necessary) 



.END START 



2.39 .HRESET 

The .HRESET request stops all I/O transfers in progress for the issuing job, 
and then performs an .SRESET request. (.HRESET is not used to clear a 
hard-error condition.) In an SJ environment, a hardware RESET instruc- 
tion is used to terminate I/O. In an FB or XM environment, only the I/O 
associated with the job that issued the .HRESET is affected by entering 
active handlers at the abort entry point of the handler. All other transfers 
continue. 

Macro Call: .HRESET 

Errors: 

None. 
Example: 

Refer to the example for .SRESET for format. 

2.40 .INTEN 

.INTEN is used by interrupt service routines to: 

1. Notify the monitor that an interrupt has occurred and to switch to 
system state. 

2. Set the processor priority to the correct value. 

3. Save the contents of R4 and R5 before returning to the Interrupt Ser- 
vice Routine. Any other registers must be saved by you. 

.INTEN issues a subroutine call to the monitor and does not use an EMT 
instruction request. 

All external interrupts must cause the processor to go to priority level 7. 
.INTEN is used to lower the priority to the value at which the device should 
be run. On return from .INTEN, the device interrupt can be serviced, at 
which point the interrupt routine returns with an RTS PC. 

NOTE 

An RTI instruction does not return correctly from an inter- 
rupt routine that specifies an .INTEN. 

Macro Call: .INTEN prio[,pic] 
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where: 



prio 



pic 



is the processor priority at which to run the interrupt routine, 
normally the priority at which the device requests an inter- 
rupt 

is an optional argument that should be non-blank if the inter- 
rupt routine is written as a PIC (position-independent code) 
routine. Any interrupt routine written as a device handler 
must be a PIC routine and must specify this argument 



Errors: 

None. 
Example: 



•TITLE SLll.MAC 



SLll.MAC - This is an example in the use of the 4INTEN request. 
The example is an in-linei interrupt service routinei which may 
be assembled separately and linked uith a mainline pro<rratn. 
The routine transfers data from a user specified buffer to a DLll 
Serial Line Interface. 



CALLING FORMAT: 





JSR 


R5.SL11 




.MQRD 


wo rdCDunt 




.WORD 


BUFFER 


BUFFER: 


.BLKW 


wo rdoount 



{Initiate Output 

t» words to transfer 

{Address of Data Buffer 



.MCALL 



. INTEN 



DLVEC 


= 304 




DLCSR 


= 17S504 




DLPRI 


= a 




SLll:: 


MOV 


(R5)+.<PC)+ 


WCNT: 


.UORD 







Moy 


<R5)+,(PC)+ 


BUFAD: 


.WORD 







ASL 


WCNT 




BEO 


1* 




MOV 


•DLINT »e»DLVEC 




BIS 


•lOO.SnOLCSR 


1$: 


RETURN 




DLINT: 


.INTEN 


DLPRI 




MOVB 


SBUFADiScDLCSR+Z 




INC 


BUFAD 




DEC 


WCNT 




BEO 


DLDUN 




RETURN 




DLDUN: 


BIC 


•100.e«DLCSR 




RETURN 






.END 





iDLU Vector »»« 
iDLll Output CSR •»» 
iDLll Priority for RT-U 



iI/O Initiation 



Get word count 



!Get address of Data Buffer 

iMake word count byte count 
iJust leave if zero word count 
ilnitialize DLll interrupt uector 
tEnable interrupts 
iReturn to caller 

ilnterrupt serulce - Notify RT-11 

iand drop priority to that of DLll 

iTransf e r a byte 

iBump buffer pointer 

lAll bytes transferred? 

iBranoh if yes 

iNo return from interrupt thru RT-11 

iAll done - disable DLll interrupts 
iReturn thru RT-11 



2.41 .LOCK/.UNLOCK 



.LOCK 

The .LOCK request keeps the USR in memory to provide any of its services 
required by your program. If all the conditions that cause swapping are 
satisfied, the part of the user program over which the USR swaps is written 
into the system swap blocks (the file SWAP.SYS) and the USR is loaded. 
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otherwise, the copy of the USR in memory is used, and no swapping occurs. 
(Note that certain calls always require a fresh copy of the USR.) A .LOCK 
request always causes the USR to be loaded in memory if it is not already 
in memory. The USR is not released until an .UNLOCK request is given. 
(Note that under an FB monitor, calling the CSI or using a .GTLIN request 
can also perform an implicit and temporary .UNLOCK.) A program that 
has many USR requests to make can .LOCK the USR in memory, make all 
the requests, and then .UNLOCK the USR. 

In an FB environment, a .LOCK inhibits the other job from using the USR. 
Note that the .LOCK request reduces time spent in file handling by elimi- 
nating the swapping of the USR in and out of memory. .LOCK causes the 
USR to be read into memory or swapped into memory. After a .LOCK has 
been executed, an .UNLOCK request must be executed to release the USR 
from memory. The .LOCK/.UNLOCK requests are complementary and 
must be matched. That is, if three .LOCK requests are issued, at least three 
.UNLOCK requests must be done, otherwise the USR is not released. More 
.UNLOCK than .LOCK requests can be issued without error. 

Macro Call: .LOCK 
Notes: 

1. It is vital that the .LOCK call not come from within the area into which 
the USR will be swapped. If this should occur, the return from the 
.LOCK request would not be to the user program, but to the USR itself, 
since the .LOCK function inhibits the user program from being re-read. 
Also, none of the executable code should be in the area or reference 
anj^hing in the area that the USR will occupy while it is locked. 

2. Once a .LOCK has been performed, it is not advisable for the program 
to destroy the area the USR is in, even if no further use of the USR is 
required, because this causes unpredictable results when an .UNLOCK 
is done. 

3. If a foreground job performs a .LOCK request while the background job 
owns the USR, foreground execution is suspended until the USR is 
available. In this case, it is possible for the background to lock out the 
foreground (see the .TLOCK request). 

Errors: 

None. 
Example: 

Refer to the example for the .UNLOCK request. 

.UNLOCK 

The .UNLOCK request releases the User Service Routine (USR) from mem- 
ory if it was placed there with a .LOCK request. If the .LOCK required a 
swap, the .UNLOCK loads the user program back into memory. There is a 
.LOCK count. Each time the user does a .LOCK, the lock count is incre- 
mented. When the user does an .UNLOCK, the lock count is decremented. 
When the lock count goes to 0, the user program is swapped back in (see 
Note 1). 
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Macro Call: .UNLOCK 
Notes: 

1. The number of .UNLOCK requests must at least match the number of 
.LOCK requests that were issued. If more .LOCK requests are done, the 
USR remains locked in memory. Extra .UNLOCK requests in your pro- 
gram do no harm since they are ignored. 

2. With two running jobs in an FB environment use .LOCK/.UNLOCK 
pairs only where absolutely necessary. When a job locks the USR, the 
other job cannot use it until it is unlocked, which can degrade perform- 
ance in some cases. 

3. In an FB environment, calling the CSI with input coming from the 
console terminal results in an implicit (though temporary) .UNLOCK. 

4. Make sure that the .UNLOCK request is not in the area that the USR 
swaps into. Otherwise, the request can never be executed. 

Errors: 

None. 
Example: 

•TITLE LOCK. MAC 



.LOCK / .UNLOCK - This is an SKample in the use of the .LOCK and .UNLOCK 
requests. This example tries to obtain as much memory as possible (usinsf 
the .SETTOP request), which uill force the USR into a swappins mode. The 
.LOCK request uill brins the USR into memori' (ouer the hish 2K of our little 
prosram !) and force it to remain there until an .UNLOCK is issued. 





.MCALL 


.LOCK (.UNLOCK i. 




.MCALL 


.SETTOP. .PRINT, 




SYSPTR=5a 


START: 


.SETTOP 
.LOCK 


e«SYSPTR 




.LOOKUP 


• AREA,»0,«FILE1 




BCC 


1» 


Zt: 


.PRINT 
.EXIT 


»LMSG 


1$: 


.PRINT 


•FIFNO 




Moy 


•AREA.RO 




INC 


BRO 




Moy 


«FILE2,2(R0) 




.LOOKUP 






BCS 


2* 




.PRINT 


•FZFND 




.UNLOCK 






.EXIT 




AREA: 


.BLKU 


3 


FILEl: 


.RAD50 


/DK/ 




.RAD50 


/PIP / 




.RAD5P 


/SAV/ 


FILEZ; 


.RAD50 


/DK/ 




.RAD50 


/TECO / 




.RAD50 


/SAV/ 



■ EXIT 



iPointer to besinnins of RMON 

iTry to allocate all of memory (up to RMON) 

ibrina USR into memory 

iLOQKUP a file on channel 

(Branch if successful 

(Print Error Message 

i then exit proSram 

•Announce our success 

iRO => EMT Arsument BlccK 

ilncrement low byte of 1st ars (chan ») 

iFill in pointer to new filespeo 

iOo the .LOOKUP from filled in ars blocR 

ipointed to by RO. 

(Branch on error 

iSay ue found it 

inou release the USR 

iand exit prosram 

iEMT Arsument BlocK 

iA File we're sure to find 



(Another file ue misht find 
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LMSG! .ASCIZ /?Error on .LOOKUP?/ iError messase 
FIFND: .flSCIZ /...Found PIP.SftV/ 
F2FND: .flSCIZ /... Found TECO . SAW/ 



.EVEN 

.END START 



2.42 .LOOKUP 



A .LOOKUP request can be used in two different ways. The first way is to 
use the request as a standard lookup, which occurs under the SJ, FB, and 
XM monitors. The second way is to use the request when the system job 
feature is implemented. Both ways are described in this section. 

2.42.1 Standard Lookup 

The .LOOKUP request associates a specified channel with a device and 
existing file for the purpose of performing I/O operations. The channel used 
is then busy until one of the following requests is executed: 

.CLOSE 

.SAVESTATUS 

.SRESET 

.HRESET 

.PURGE 

.CSIGEN (if the channel is in the range 0-10 octal) 

Note that if the program is overlaid, channel 17(octal) is used by the over- 
lay handler and should not be modified. 

If the first word of the file name (the second word of dblk) is and the 
device is a file-structured device, absolute block of the device is desig- 
nated as the beginning of the file. This technique is called a non-file-struc- 
tured .LOOKUP and allows I/O operations to access any physical block on 
the device. If a file name is specified for a device that is not file structured 
(such as LPrFILE.TYP), the name is ignored. 

The handler for the selected device must be in memory for a .LOOKUP. On 
return from the .LOOKUP, RO contains the length in blocks of the file just 
opened. On a return from a .LOOKUP for a non-directory, file-structured 
device (typically magtape), RO contains for the length. 

NOTE 

Care should be exercised when doing a non-file-structured 
.LOOKUP on a file-structured device, since if your program 
writes data, corruption of the device directory can occur and 
effectively destroy the disk. (The RT-11 directory starts in 
absolute block 6.) 

In particular, avoid doing a .LOOKUP or .ENTER with a file 
specification where the file value is missing. If the device 
type is not known in advance and is to be entered from the 
keyboard, include a dummy file name with the .LOOKUP or 
.ENTER, even when it is assumed that the device is always 
non-file structured. 
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Macro Call: .LOOKUP area,chan,dblk[,seqnum] 
where: 



area 
chan 
dblk 



is the address of a three-word EMT argument block 

is a channel number in the range 0-377(octal) 

is the address of a four-word Radix-50 descriptor of the 
file to be operated upon 



seqnum is a file number for magtape and cassette 

If this argument is blank, a value of is assumed. 

For magtape, it describes a file sequence number. The ac- 
tion taken depends on whether the file name is given or is 
null. The sequence number can have the following values: 

-1 means suppress rewind and search for a file name 
from the current tape position. If a file name is given, 
a file-structured lookup is performed (do not rewind). 
It is important that only -1 be specified and not any 
other negative number. If the file name is null, a non- 
file-structured lookup is done (tape is not moved). 







n 



means rewind to the beginning of the tape and do a 
non-file-structured lookup. 

where n is any positive number. This means position 
the tape at file sequence number n and check that the 
file names match. If the file names do not match, an 
error is generated. If the file name is null, a file-struc- 
tured lookup is done on the file designated by seqnum. 



Request Format: 



RO 



area: 



chan 



dblk 



seqnum 



Errors: 

Code Explanation 

Channel already open. 

1 File indicated was not found on the device. 
Example: 

.TITLE LOOKUP. MAC 



.LOOKUP - This is an example in the use of the .LOOKUP request. 
This example determines whether or not the RT-11 Devioe Queue 
Horkfile exists on deuioe DKi and If so ■ prints its size in 
blocKs on the console terminal. 
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START! 



1*1 



CNMIO: 
1*: 



2t: 



AREA: 
OUSPEC: 

BUFF: 
SIZE: 
NOFIL: 



.MCALL 

.LOOKUP 

BCC 

.PRINT 

.EXIT 

MOM 

CALL 

.PRINT 

.EXIT 

MOV 

CLR 

INC 

SUB 

BGE 

ADD 

DEC 

BED 

CALL 

MOWB 

RETURN 

.BLKW 

.RAD50 

.RAD50 

.ASCII 

.ASCIZ 

.ASCIZ 

.EVEN 

.END 



.LOOKUP. .PRINT. .EXIT 

ibiK -'^lo. 

•AREA.»0(«OUSPEC 
1$ 

•NOFIL 

•SIZEfRl 
CNVIO 

«BUFF 

RO.-(SP) 

RO 

RO 

• 10. .esp 

It 

«72,eSP 

RO 

2$ 

CNVIO 

(SP)+.(Rn + 



iSee if there's a DK :OUFILE.TMP 

iBranch if there is 

iPrint 'File Not Found' message 

!then exit prosfram 

iRl => where to put ASCII size 

iConwert size (in RO) to ASCII 

iPrint size of OUFILE.TMP on console 

ithen exit prosraM 

{Subroutine to oonuert Binary • in RO 

!to DeciMal ASCII by repetitive 

isubt ract ion . The remainder for each 

iradix is Made into ASCII and pushed 

ion the stacKi then the routine calls 

iitself. The code at 2* pops the ASCII 

idisits off the staoK and into the out- 

iput buffer, eventually returnins to 

ithe oallins prosram. This is a VERY 

iuseful routine, is short and is 

imewo ry efficient. 



(iEMT Arsument BlcoK 



JdK \Qu4iLE/ 

/TMP/ 

/DK:QUFILE,TMP = / 

/ Blocks/ 

/?File Not Found DK !OUFILE .TMP ?/ 

START 



2.42.2 System Job Lookup 

The foreground and background jobs can send messages to each other via 
the existing .SDAT/.RCVD/.MWAIT facihty. A more general message facil- 
ity is available to all jobs through the message queue (MQ) handler. By 
turning message handling into a formal "device" handler, and treating 
messages as I/O to jobs, the existing .READ/C/W-.WRITE/CAV-.WAIT 
mechanism can be used to transmit messages. A channel is opened to a job 
via a .LOOKUP request, after which standard I/O requests are issued to 
that channel. 

Macro Call: .LOOKUP area,chanjobdes 

where: 

area is the address of a two-word EMT argument block 

chan is the number of the channel to open 

jobdes is the address of a four-word descriptor of the job to which 
messages will be sent or received 

jobdes -^ .RAD50 /MQ/ 

.ASCII /logical-job-name/ 

where logical-job-name can be from one to six characters 
long. It must be padded with nulls if less than six characters 
long. If logical-job-name is zero, the channel will be opened 
for .READ/C/W requests only and such requests will accept 
messages from any job 
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Request Format: 
RO -> area: 



chan 



jobdes 



The .LOOKUP request associates a channel with a specified job for the 
purposes of sending inter-task messages. RO is undefined on return from 
the .LOOKUP. 



Errors: 

Code 

1 
Example: 



Explanation 

Channel already open. 
No such job. 



.TITLE SJLOOK.MAC 



.LOOKUP - Thi5 is an example in the use of the .LOOKUP reiuest 
to open a message ohannel to a System Jobi spec i f i cal ly > the 
RT-11 Device Queue Foreground program. NOTE: This example assumes 
it will be run under an FB Monitor Senerated with System Job 
Support and that QUEUE. REL has been successfully FRUN/SRUN !!! 



START: 



1»: 



2$: 



AREA: 
QMSG: 



RMSG: 

MSGERR: 
NO JOB: 
QRUN: 



.MCALL 

.LOOKUP 

BCC 

.PRINT 

.EXIT 

.WRITW 

BCS 

.READU 

BCS 

•PRINT 

.EXIT 

.PRINT 

.EXIT 

.BLKM 

.RAD50 

.ASCIZ 

.UORD 

.MORD 

.ASCII 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.EI.IEN 

.END 



.LOOKUP..PRINT..EXIT..WRITW..READW 



»AREA>*0i«OMSG 

1$ 

•NDJOB 

»AREA>«0i«RMSG>»6 

Z$ 

•AREA ("O iHRMSG i«6 

2* 

«QRUN 

•MSGERR 



iTry to open a channel to QUEUE 

iBranch if successful 

lErro r . . 1 p rint error messase 

ithen exit pro 3 ram 

iSend a meaninsrless messaife to QUEUE 

iBranch if error 

!Mait for an acKnowl eddment messasfe 

iBranch if error 

iAnnounce QUEUE aliue and well 

iThen exit 

iPrint error message 

iThen exit 



iEMT ArSuwent Block 

iJob Descriptor BlocK for .LOOKUP 



iOumfflv message 



5 

/MO/ 

/QUEUE/ 

0)0 



/SJLOOK/ 

/?Messa*e Error?/ iError Messages > etc. 

/?QUEUE is not runninS?/ 

/! QUEUE is aliue and runnins !/ 

START 



2.43 .MAP (XM Only) 



The .MAP request maps a previously defined address window into a dy- 
namic region of extended memory or into the static region in the lower 28K 
words of memory. If the window is already mapped to another region, an 
implicit unmapping operation is performed (see the .UNMAP programmed 
request). 
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Macro Call: .MAP area[,addr] 

where: 

area is the address of a two-word EMT argument block 

addr is the address of the window definition block containing a 
description of the window to be mapped and the region to 
which it will map 

Request Format: 

RO -^ area: 



36 



addr 



Errors: 

Code Explanation 

2 An invalid region identifier was specified. 

3 An invalid window identifier was specified. 

4 The specified window was not mapped because the offset is 
beyond the end of the region, the region is larger than the 
window, or the window would extend beyond the bounds of 
the region. 

Example: 

Refer to example for the .CRAW request. 

2.44 .MFPS/.MTPS 

The .MFPS and .MTPS macro calls allow processor-independent user access 
to the processor status word. The contents of the registers are preserved 
across either call. 

The .MFPS call is used to read the priority bits only. Condition codes are 
destroyed during the call and must be directly accessed (using conditional 
branch instructions) if they are to be read in a processor-independent 
manner. 

In the XM monitor, .MFPS and .MTPS can be used only by privileged jobs 
and are not available for use by virtual jobs. 

Macro Call: .MFPS addr 

where: 

addr is the address into which the processor status is to be stored; 
if addr is not present, the value is returned on the stack. Note 
that only the priority bits are significant 

The .MTPS call is used to set the priority bits. 

Macro Call: .MTPS addr 
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where: 



addr 



Note: 



is either the value or the address of the value (depending on 
addressing mode) to be placed in the PSW. If addr is not 
present, the processor status word is taken from the stack. 
Note that the high byte on the stack is set to when addr is 
present. If addr is not present, you should set the stack to the 
appropriate value. In either case, the lower byte on the stack 
is put in the processor status word 



It is possible to perform MTPS and MFPS operations and access the condi- 
tion codes by following this special technique: 

1. In the beginning of your program, set up the lOT trap vector as 
follows: 



20 



.ABECT 




.HORD 


GETPS 


.UQRD 


340 



;SET UP IDT 

HOT SERVICE ADDRESS IN 'MFPS' SUBROUTINE 
i PRIORITY 7 



2. Elsewhere in your program place the following routines: 



i + 

1 MFPS/MTPS ROUTINES . . . 



MFPS: IDT 



iEXECUTE lOT 

iWILL RETURN TO CALLER M/ PS ON STACK 



GETPS: MOV 4<SP)t@SP iPUT USER RETURN ON TOP 

MOV Z(SP)f4(SP) iMOVE PS SAVED BY lOT 
MTPS: RTI ;WILL RETURN TO CALLER W/ NEW PS 

3. To get the PSW or to set the PSW to a desired value, follow this 
sequence of instructions: 

i + 

i TO GET PS . . . 



JSR PCfMFPS 



iGET PS 

■CONTINUE. PS IS ON STACK . 



) + 



i TO PUT PS . . . 
i- 






MOV 


NEI>IPS(-(SP) 


5PUT DESIRED PS ON STACK ... 


JSR 


PC. MTPS 


!CALL MTSP 

;CONTINUE PROCESS N/ NEN PS . . . 


Errors: 






None. 
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Example: 



.TITLE MFPS 



.MFPS / 4MTPS - This is an example in the use of the .MFPS and .MTPS 
requests. The e»ample is a skeleton Mainline prostram which calls a 
subroutine to Set the next free element in an RTll-liKe linked queue. 



.MCALL .MFPS.. MTPS.. EXIT.. PR I NT.. TTINR 

JSM = 44 iJob Status Mord location 

TTSPC* = 10000 ilTY Special bit 



START: 



{Skeleton mainline program... 





BIS 

i 


•TTSPC*. 

* 


>e»JSM 


iSet TTY Special bit 




1 

CALL 


GETOUE 






iCall subroutine to return next free 
ielement - on return R5 => element 




BCC 


1* 






iBranoh if no error 




.PRINT 


•NOELEM 






iNo more elements available 




BIC 


•TTSPC*. 


ie«jsw 


iReset special bit 




.EXIT 








iExit program 


1»: 


NOP 
NOP 








iProiram continues 




.PRINT 


• GDTl 






iAnnounce success 


Z$: 


.TTINR 

BCS 

BR 


2* 
START 






iMait for a key to be hit on console 


GETOUE: 


Moy 


ttOHEADiR4 




iPoint to queue head 




TST 


SRa 






iOueue exhausted? 




BEO 


11* 






iYes...set error on leaving 




.MFPS 








iSaue status on stack 




.MTPS 


• 330 






iRaise priority to 7 




Moy 


SRa.RS 






iR5 points to next element 




Moy 


SRS.SRd 






IRelink the queue 




.MTPS 








;Restore previous status 




TST 


(PC) + 






!This clears carry & skips next instruction 


11*: 


SEC 
RETURN 








ISet carry bit (to flas error) 
.Return to caller 


QHEADi 


.MORD 01 








iOueue head 


Ql: 


.UORD 02 


.0.0 






■3 linked queue elements 


02: 


.WORD 03 


.0,0 








03: 


.WORD 0.0.0 








NOELEM: 


.ASCIZ 


/?Nd more 


Oueue 


Elements Available?/ 


GOTl: 


.ASCIZ 


/Element 




aoqui re 


id. ..press any key to continue/ 



.END 



START 



2.45 .MRKT (FB and XM; SJ Monitor Special Feature) 

The .MRKT request schedules a completion routine to be entered after a 
specified time interval (measured in clock ticks) has elapsed. The .MRKT 
request is an optional feature in the SJ monitor, and is selected as a system 
generation option. 

A .MRKT request requires a queue element taken from the same list as the 
I/O queue elements. The element is in use until either the completion rou- 
tine is entered or a cancel mark time request is issued (see .CMKT request). 
The user should allocate enough queue elements to handle at least as many 
mark time and I/O requests as are expected to be pending simultaneously. 
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Macro Call: .MRKT area,time,crtn,id 

where: 

area is the address of a four-word EMT argument block 

time is the address of a two word-block containing the time inter- 
val (high order first, low order second), specified as a number 
of clock ticks 

crtn is the entry point of a completion routine 

id is a non-zero number or memory address assigned by the user 

to identify the particular request to the completion routine 
and to any cancel mark time requests. The number must not 
be within the range 177000-177777, which is reserved for 
system use. The number need not be unique (several .MRKT 
requests can specify the same id). On entry to the completion 
routine, the id number is in RO 

Request Format: 
RO 



area: 


22 







time 




crtn 




id 



Errors: 

Code Explanation 

No queue element was available. 

Example: 

.TITLE TREAD. MAC 



.MRKT/.CMKT - This is an example in the use of the .MRKT/.CMKT reiuests 
The example illustrates a user implemented "Timed Read" to cancel an 
input re^iuest after a specified time interual. 



START: 

1«! 



2$: 



.MCALL 

LF = 12 
JSW = 4a 
TCBIT$ = 
TTSPC* = 

.OSET 

MOV 

MOV 

CALL 

BCS 

.PRINT 
BR 

.PRINT 

.EXIT 



,MRKT ..TTINR1.EXIT..PRINT..TTYOUT..CMKT..TWAIT..OSET 



100 
10000 



• XQUE >«1 
»FR0MT>R0 
■BUFFR.Rl 
TREAD* 

2* 

• LINE 
1$ 
•TIMDUT 



ILine Feed 

iJob Status Uord location 
iReturn C-bit bit in JSW 
!TTY Special Mode bit in JSW 

iNeed an extra O-Elem for this 

iMainline - RO => Prompt 

iRl => Input buffer 

iDo a "timed read" 

iC-bit set " Timed out 

i "Process" data... 

;Gd bacK for more 

iRead timed out - could process 

■partial data but ue'll Just exit 



i» TREAD* - 

;* Input: 

;• 

>» Output: 



"Timed Read" Subroutine 
RO => Prompt StrinS / RO = if no prompt 
Rl => Input Buffer 

Buffer contains input charsi if anv i terminated 
by a null char. C-Bit set if timed out 
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TREAD*: 



1$: 



TTIN; 



TBYT: 



2»: 

3»: 



TOUT! 

KOUE: 

AREA: 

TAREA: 

TIME: 

WAIT: 

LINE: 

BUFFR: 

PROMT: 

TIMOUT: 



TST 

BEQ 

■PRINT 

CLR 

.MRKT 

BIS 

CLRB 

.TWAIT 

.TTINR 

BIT 

.MORD 

BNE 

BCS 

MOVB 

.CMKT 

BIS 

.TTINR 

MOMB 

BCC 

CLRB 

BIC 

ROR 

RETURN 

INC 

RETURN 

.BLKM 

.UORD 

.BLKU 

.MORD 

.MORD 

.ASCII 

.BLKB 

.ASCIZ 

.ASCIZ 

.END 



RO 
1$ 

TBYT 

• TAREA ."TIME .STOUT ,«1 
•TCBIT».B»JSW 
SRI 

• AREA 

• 1 i(PC) + 


2* 

TTIN 
RO.tRl )+ 

• TAREA >S0 
»TTSPC*.@«JSW 



RO .(Rl ) + 

3* 

-(Rl) 

•TCBITtlTTSPCt 

TBYT 

TBYT 



See if 
Branch 
Output 
Clear 
Issue 
Set C 
Start 
Mait s 
LooK f 
Timed 
Time-o 
Branch 
Branch 
Xfer 1 
Cance 1 
Tu rn 
Flush 
putt in 
i If wo r 
iTe riiiin 
@«JSW iClear 
iSet ca 
iRe t u rn 



n 



I F 



we haue to prompt 

if no . . . 

p rompt 
t ime-out f lad 
a .MRKT for 10 sec 
Bit bit in JSW (for F/B) 
with "empty" buffer 
we don't locK out BG 
era characte r 
out? 
ut flas 

if yes 

if input not complete 
St characte r 

.MRKT 
n TT : Spec ial mode 
TT : rin 3 buf f e r 
£f characters in user buffer 
e char, do de t 'em 
ate input with null byte 
bits in JSU 
rry if timed out 

to caller 



10. 
O.WAIT 

a 

O.GOO. 

0.1 

/Not in stock - Part • 

81. 

/Enter Part » >/<200> 

/Timed read OHPlred!/ 

START 



iLeaue completion code 

lEx t ra 0-El ement 

iEMT Arsument blooK for .TWAIT 

iEMT Arsument blooK for .MRKT 

iTime-out interval (10 sec) 

il/SO sec wait between .TTINRs 

/ iDummy response 
iUse r input buf f e r 
iPrompt 
SToo bad message 



2.46 .MTATCH (Special Feature) 

The .MTATCH request attaches a terminal for exclusive use by the re- 
questing job. This operation must be performed before any job can use a 
terminal with multi terminal programmed requests, although a job can is- 
sue a .MTGET request before a .MTATCH. If .MTATCH request fails be- 
cause the terminal is owned by another job, the job number of the owner is 
returned in RO. 

Macro Call: .MTATCH area,addr,unit 

where: 

area is the address of a three-word EMT argument block 

addr is the optional address of an asynchronous terminal status 
word, or it must be #0 (The asynchronous terminal status 
word is a special feature that you can select during the sys- 
tem generation process.) 

unit is the logical unit number of the terminal (The logical unit 
number is the number assigned by the system to a particular 
physical unit during the system generation process.) 

Request Format: 



RO 



area: 



37 5 


addr 


unit 
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Errors: 



Code 

2 
3 
4 
5 

Example: 



Explanation 

Nonexistent logical unit number. 

Invalid request; function code out of range. 

Unit attached by another job (job number returned in RO). 

In the XM monitor, the optional status word address is not 
in valid user virtual address space. 



MTXAMPtMAC - The follouins is an example proSrant that 
demonstrates the use of the mul t i te rminal 
programmed re<iuests< The program attaches all the 
terminals on a Siyen systewt then proceeds with an 
input/echo eKercise on all attached terminals until 
CTRL/C is sent to it. 



•MCALL 


•MTATCH. 


.MTPRNT.. 


MTGE 


T..MTIN..MTOUT 


.MCALL 


.PRINTf. 


MTRCTO.. MTSET 


..MTSTAT. .EXIT 


HNGUP* 


= 4000 






.Terminal off-line bit 


TTSPC* 


= 10000 






iSpecial mode bit 


TTLC* 


= 40000 






iLouer-case mode bit 


AS.INP 


= 40000 






i Input auai lable bit 


M.TSTS 


= 






.Terminal status word 


M.TSTW 


= 7 






.Terminal state byte 


M.NLUN 


= 4 






itt of LUNs word 


MTXAMP; 








iStart of program 




.MTSTAT 


«MTA.«MSTAT 


iGet MTTY status 




MOV 


MSTAT+M. 


NLUN 


,R4 iR4 = » LUNs 




BEO 


MERR 




iNone? Not MTTY! ! ! 




CLR 


Rl 




.Initial LUN = «0 




MOV 


«AST .R2 




;R2 -^ AST word array 


10«: 


, MTATCH 


•MTA.R2 


Rl 


.Attach terminal 




BCC 


20* 




{Success! 




CLRB 


TAKRl) 




.Set attach failed 




BR 


30* 




.Proceed with next LUN 


20*: 


MOyB 


«1 .TAKRl) 


.Attach successful 




Moy 


Rl .R3 




iCopy LUN 




ASL 


R3 




.Multiply by B for offse 




ABL 


R3 




.to the terminal status 




ASL 


R3 




iblocK. . . 




ADD 


•»TSB.R3 




!R3 -* LUN's TSB 




•MTGET 


«MTA.R3 


.Rl 


iGet LUN's status 




BIS 


«TTSPC*+TTLC* .M.TBTS(R3) iSet special 










imode and lower case 




.MTSET 


• MTA .R3 


.Rl 


•Set LUN's status 




BITB 


•HNGUP*/400. 


M.TSTN(R3) !Dn line? 




BNE 


30* 




•Nope! 




.MTRCTO 


«MTA .Rl 




.Reset CTRL/0 




.MTPRNT 


«MTA.«HELLO. 


Rl iSay hello. . . 


30*: 


ADD 


«2.R2 




!R2 -* Next AST word 




INC 


Rl 




iGet next LUN 




CMP 


Rl >R4 




.Done? 




BLO 


10* 




iNope. so attach another 
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LOOP: 



10*! 



20«: 



ERR: 
MERR; 

AST: 

TAI : 



MSTAT: 
TSB; 

MTA: 
MTCHAR: 

HELLO; 

NOMTTY: 
UNEXP: 



CLR 

MOV 

TST5 

BEO 

BIT 

BEO 

.MTIN 

BCS 

.MTOUT 

BCS 

ADD 

INC 

CMP 

BLO 

BR 

.PRINT 
• EXIT 
.PRINT 
.EXIT 

.BLKM 

.BLKB 



.BLKU 

.BLKW 

.BLKU 
.BYTE 

.ASCII 
.ASCIZ 
.ASCIZ 
.ASCIZ 



Rl 

•AST.R2 

TAKRl) 

20$ 

»AS.INPt(R2) 

20* 



ilnput & echo foreuer 
Jlnitial LUN = 
iR2 -* AST words 
iTerhiinal attached? 
iNope . • • 
iAny input? 
iNope . . < 



#MTA f«MTCHAR (Rl i»l ilnput a character 
ERR iOoops! Error on input 

»MTA »«MTCHAR >R1 t«l iEoho the character 
ERR iOoops! Error on output 

»2 tR2 iPoint to next AST word 

Rl iGet next LUN 

Rl tR4 (Done them all? 

10* )No I <ro checK another 

LOOP iYes t repeat (foreuer!) 



»UNEXP 
•NOMTTY 

16. 
16. 



8. 
1G.#4. 



lUnexpec ted error... 
iPrint message & exit! 
iNot mul t i t e rminal 
iPrint messasle & exit 

i Asynoh ronous Terdiinal 
.Status l«lords (1/LUN) 
iTerminal attached list 
! 1 Byte per LUN. . . 
iO = Not attached 
iMTTY status block 
iTerminal status blocKs 
i 16. blooKs cf 4 words 
iEMT arsuntent blooK 
iCharacter stored here 



<33>"H"<33>"J" ;<,"T52 Home + Erase to EOS 
/Hello! Characters typed will be echoed/ 
/?Not mul t i te rminal system?/ 
/?Unexpected e r ro r . . . p ro Sram abortinS?/ 



.END 



MTXAMP 



iEnd of proSram 



2.47 .MTDTCH (Special Feature) 

The .MTDTCH request detaches a terminal from one job and makes it 
available for other jobs. When a terminal is detached, it is deactivated, and 
unsolicited interrupts are ignored. Input is disabled immediately, but any 
characters in the output buffer are printed. Attempts to detach a terminal 
attached by another job result in an error. 

Macro Call: .MTDTCH area,unit 

where: 

area is the address of a three-word EMT argument block 

unit is the logical unit number (lun) of the terminal to be detached 

Request Format: 
RO -> area: 



37 6 


unused 


— unit 
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Errors: 

Code 

1 

2 

3 

Example: 



Explanation 

Invalid unit number, unit not attached. 

Nonexistent logical unit number. 

Invalid request; function code out of range. 



.MCALL .MTDTCH i .MTPRNT . .MTATCH .. EXI T .. PRINT 



START; 





.MTATCH «MTA.»0.«3 


iATTACH TO LUN 3 




BCS 1$ 


!ATTACH ERROR 




.MTPRNT MTA »»MESS ,«3 


iPRINT MESSAGE 




.MTDTCH «MTA.*3 


iDETACH LUN 3 




.EXIT 




1«: 


.PRINT «ATTERR 
.EXIT 


iATTACH ERROR 

! (PRINTED ON CONSOLE) 


ATTERR: 


.ASCI2/ATTACH ERROR/ 




MESS! 


.ASCIZ/DETACHING TERMINAL/ 
.EUEN 




MTAi 


.BLKW 3 
.END START 





2.48 .MTGET (Special Feature) 

The .MTGET request returns the status of the specified terminal unit to the 
caller. If a .MTGET request fails because the terminal is owned by another 
job, the job number of the owner is returned in RO. You do not need to do an 
.MTATCH before using the .MTGET request. 

Macro Call: .MTGET area,addr,unit 

where: 

area is the address of a three-word EMT argument block 

addr is the address of a four-word status block where the status 
information is returned 

unit is the logical unit number (lun) of the terminal whose status 
is requested. A unit need not be attached to the job issuing a 
.MTGET request. If the unit is attached to another job (error 
code 4), the terminal status will be returned and the job num- 
ber will be contained in RO. In any other error condition, the 
contents of RO are undefined 

Request Format: 

RO — > area: 



37 1 1 


addr 


— 1 unit 
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The status block has the following structure: 
addi^-> 



M.TSTS 



M.TST2 



M.FCNT 



M.TSTW 



M.TFIL 



M.TWID 



The following information is contained in the status block: 

Byte Offset Description 

(M.TSTS) Terminal configuration word 1 

2 (M.TST2) Terminal configuration word 2 

4 (M.TFIL) Character requiring fillers 

5 (M.FCNT) Number of fillers 

6 (M.TWID) Carriage width 

7 (M.TSTW) Terminal status byte 

Note that if an error occurs, and the error code is not 1 or 4, the status block 
will not have been modified. 

NOTE 

Use the Bit Set (BIS) and Bit Clear (BIC) instructions in- 
stead of Move (MOV) and Clear (CLR) instructions when set- 
ting terminal and line characteristics. This avoids changing 
other bits inadvertently. 

The bit definitions for terminal configuration word 1 (M.TSTS) are as fol- 
lows: 



Value 



Bit 



1 





2 


1 


4 


2 


10 


3 


100 


6 


200 


7 


7400 


8-11 



Meaning 

Terminal has hardware tab 
Output RET/LF when carriage width exceeded 
Terminal has hardware form feed 
Process CTRL/F and CTRL/B (and CTRL/X if system 
job) as special command characters (if clear, CTRL/F 
and CTRL/B are treated as ordinary characters) 
Inhibit TT wait (similar to bit 6 in the Job Status Word) 
Enable CTRL/S-CTRL/Q processing 
Line speed (baud rate) mask. Bits 8 through 11 indicate 
the terminal baud rate (DZll and DZVll only). The val- 
ues are as follows: 

Octal Value of 
Line Speed Mask 



^S bits 11-8) 


Baud Rate 


0000 


50 


0400 


75 


1000 


110 


1400 


134.5 


2000 


150 


2400 


300 
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Octal Value of 
Line Speed Mask 
(M.TSTS bits 11-8) 
3000 
3400 
4000 
4400 
5000 
5400 
6000 
6400 
7000 
7400 



Baud Rate 
600 
1200 
1800 
2000 
2400 
3600 
4800 
7200 
9600 
(unused) 



10000 12 Character mode input (similar to bit 12 in the Job 

Status Word) 

Terminal is remote (Read-only bit) 
Lowercase to uppercase conversion disabled 
Use backspace for rubout (video type display) 

The bit definitions for terminal configuration word 2 (M.TST2) are as fol- 

Meaning 

Character length, which can be 5(00), 6(01), 7(10), or 

8(11) bits (DZ only) 

Unit stop, which sends one stop bit when clear, two stop 

bits when set (DZ only) 

Parity enable (DZ only) 

Odd parity when set; even parity when clear 

Reserved 

Read pass all 

Reserved 

Write pass all 

definitions for terminal status byte (M.TSTW) are as follows: 

Meaning 

Terminal is shared console 

Terminal has hung up 

Terminal interface is DZll 

Double CTRL/C was struck (the .MTGET request resets 

this bit in the terminal control block if it is on) 

Terminal is acting as console 



20000 


13 


40000 


14 


100000 


15 


The bit c 


iefiniti 


lows: 




Value 


Bit 


3 


0-1 


4 


2 


10 


3 


20 


4 


140 


5-6 


200 


7 


77400 


8-14 


100000 


15 


The bit d 


lefinitii 


Value 


Bit 


2000 


10 


4000 


11 


10000 


12 


40000 


14 



100000 15 



Errors: 



Code Explanation 

1 Invalid unit number, unit not attached. 

2 Nonexistent logical unit number. 

3 Invalid request; function code out of range. 

4 Unit attached by another job (job number returned in RO). 
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5 In the XM monitor, the status block address is not in valid 

user virtual address space. 

Example: 

Refer to the example for the .MTATCH request. 



2.49 .MTIN (Special Feature) 



Bite 


Bit 12 








1 





1 


1 





1 



The .MTIN request reads characters from the keyboard buffer. It is the 
multiterminal form of the .TTYIN request. The .MTIN request moves one 
or more characters from the input ring buffer to a buffer specified by you. 
The terminal must be attached. An updated user buffer address is returned 
in RO if the request is successful. If bit 6 is set in the M.TSTS word (see the 
MTSET request), the .MTIN request returns immediately with the carry 
bit set (code 0) if there is no input available. Operation is similar for the 
system console if bit 6 is set in the JSW. If bit 12 in M.TSTS is clear, no line 
is available; if bit 12 is set, there are no characters in the buffer. If these 
conditions do not exist, the .MTIN request waits until input is available, 
and the job is suspended until input is available. 

The meaning of bits 6 and 12 in the terminal configuration word (M.TSTS) 
for the programmed request .MTIN is as follows: 

Meaning 

Normal mode of input (echo provided); wait for line 
Carry bit set: no line available 

Carry bit set: no character available; no echo provided 
No echo provided 

If a multiple-character request was made and the number of characters 
requested are not available, the request can either wait for the characters 
to become available, or it can return with a partial transfer. If bit 6 of 
M.TSTS is clear, the request waits for more characters. If bit 6 is set, the 
request returns with a partial transfer. In the latter case, RO contains the 
updated buffer address (pointing past the last character transferred), the C 
bit is set, and the error code is 0. 

The .MTIN request has the following form: 

Macro Call: .MTIN area,addr,unit[,chrcnt] 

where: 

area is the address of a three-word EMT argument block 

addr is the byte address of the user buffer 

unit is the logical unit number of the terminal input 

chrcnt is a character count indicating the number of characters to 
transfer. The valid range is from 1 to 255(decimal). A char- 
acter count of zero means one character 
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Request Format: 
RO 



area: 



37 2 


addr 


chrcnt unit 



Errors: 



Code 



1 
2 
3 

5 



Explanation 

No input available — bit 6 is set in the Job Status Word (for 
the system console) or in M.TSTS by the .MTSET request. 

Invalid unit number, unit not attached. 

Nonexistent logical unit number. 

Invalid request; function code out of range. 

In the XM monitor, the user buffer address is not in valid 
user virtual address space. 



Example: 

Refer to the example for the .MTATCH request. 

2.50 .MTOUT (Special Feature) 

The .MTOUT request transfers characters to the terminal output buffer. 
This request is the multiterminal form of the .TTYOUT request. The 
.MTOUT request moves one or more characters from the user's buffer to the 
output ring buffer of the terminal. The terminal must be attached. An 
updated user buffer address is returned in RO if the request is successful. 
When there is no room in the output ring buffer, the carry bit is set and an 
error code of is returned in byte 52 if bit 6 is set in M.TSTS. Otherwise, 
the job is suspended until room becomes available. 

If a multiple-character request was made and there is not enough room in 
the output ring buffer to transfer the requested number of characters, the 
request can either wait for enough room to become available, or it can 
return with a partial transfer. If bit 6 in M.TSTS is clear, the request waits 
until it can complete the full transfer. If bit 6 is set, the request returns 
with a partial transfer. In the latter case, RO contains the updated buffer 
address (pointing past the last character transferred), the C bit is set, and 
the error code is 0. 

The meaning of bit 6 in the terminal configuration word (M.TSTS) for the 
.MTOUT request is as follows: 

Bit 6 Meaning 

Normal mode for output; wait for room in buffer 

1 Carry bit set: no room in output ring buffer 
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Macro Call: 

where: 

area 
addr 
unit 
chrcnt 



.MTOUT area,addr,unit[,chrcnt] 

is the address of a three-word EMT argument block 

is the address of the caller's input buffer 

is the unit number of the terminal 

is a character count indicating the number of characters to 
transfer. The valid range is from 1 to 255(decimal) 



Request Format: 
RO -> area: 



37 3 


addr 


chrcnt | unit 



Errors: 

Code 

1 
2 
3 
5 



Explanation 

No room in output buffer. 

Invalid unit number, unit not attached. 

Nonexistent logical unit number. 

Invalid request; function code out of range. 

In the XM monitor, the user buffer address is not in valid 
user virtual address space. 



Example: 

Refer to the example for the .MTATCH request. 

2.51 .MTPRNT (Special Feature) 

This .MTPRNT request allows one or more lines to be printed at the speci- 
fied terminal in a multiterminal environment. It is equivalent to the 
.PRINT request (see .MTSET request for more details). The string to be 
printed must be terminated with a null byte or a 200 byte, similar to the 
string used with the .PRINT request as follows: 



or 



.ASCIZ /string/ 
.ASCII /string/<200> 



The null byte causes a carriage return/line feed combination to be printed 
after the string. The 200 byte suppresses the carriage return/line feed com- 
bination and leaves the carriage positioned after the last character of the 
string. The request does not return until the transfer is complete. 

Macro Call: .MTPRNT area,addr,unit 
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37 1 7 


addr 


— unit 



where: 

area is the address of a three-word EMT argument block 

addr is the starting address of the character string to be printed 

unit is the unit number associated with the terminal 

Request Format: 
RO -> area: 

Errors: 

Code Explanation 

1 Invalid unit number, unit not attached. 

2 Nonexistent logical unit number. 

3 Invalid request; function code out of range. 

5 In the XM monitor, the character string address is not in 

valid user virtual address space. 

Example: 

Refer to the example for the .MTATCH request. 

2.52 .MTPS 

See .MFPS/.MTPS (Section 2.44). 

2.53 .MTRCTO (Special Feature) 

The .MTRCTO request resets the CTRL/0 switch of the specified terminal 
and enables terminal output in a multiterminal environment. It is equiva- 
lent to the .RCTRLO request. 

Macro Call: .MTRCTO area.unit 

where: 

area is the address of a three-word EMT argument block 
unit is the unit number associated with the terminal 

Request Format: 
RO —> area: 



37 I 4 



unused 



unit 
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Errors: 

Code Explanation 

1 Invalid unit number, unit not attached. 

2 Nonexistent logical unit number. 

3 Invalid request; function code out of range. 
Example: 

Refer to the example for the .MTATCH request. 

2.54 .MTSET (Special Feature) 

This multiterminal request sets terminal and line characteristics. It also 
determines the input/output mode of the terminal service requests for the 
specified terminal. 

Macro Call: .MTSET area,addr,unit 

where: 

area is the address of a three-word EMT argument block 

addr is the address of a four-word status block containing the line 
and terminal status being requested 

unit is the logical unit number associated with the line and termi- 
nal 

Request Format: 

RO -^ area: 



37 1 1 


addr 


— unit 



When the program returns from the request, the status block contains the 
following information: 

Byte Offset Contents 

Terminal configuration word 1 (The bit definitions 

are the same as those for the .MTGET request.) 

2 Terminal configuration word 2 (The bit definitions 

are the same as those for the .MTGET request.) 

4 Character requiring fillers 

5 Number of fillers 

6 Carriage width (byte) 
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NOTE 

The .MTSET request sets all of the parameters listed above. 
The recommended procedure for using .MTSET is: (1) precede 
it by an .MTGET request; (2) use BIS and BIC instructions to 
set or clear bit fields (modify only the bits or bytes that you 
intend to change); (3) issue the .MTSET request to replace 
the previous terminal status with the updated status. 

Note that if an error occurs, and the error code is not 1, the status block will 
not have been modified. 

Errors: 

Code Explanation 

1 Invalid unit number, lun not attached. 

2 Nonexistent logical unit number. 

3 Invalid request, function code out of range. 

5 In the XM monitor, the status block address is not in valid 

user virtual address space. 

Example: 

Refer to the example for the .MTATCH request. 

2.55 .MTSTAT (Special Feature) 

The .MTSTAT request returns multiterminal system status information. 

Macro Call: .MTSTAT area,addr 

where: 

area is the address of a three-word EMT block 

addr is the address of an eight-word status block where multiter- 
minal status information is returned. The status block con- 
tains the following information: 

Byte Offset Contents 

Offset from the base of the resident monitor 

to the first terminal control block (TCB) 

2 Offset from the base of the resident monitor 

to the terminal control block of the console 
terminal for the program 

4 The value (0-16 decimal) of the highest logi- 

cal unit number (LUN) built into the system 

6 The size of the terminal control block in 

bytes 

10-17 Reserved 
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Request Format: 



RO 



area: 



37 



10 



addr 



Errors: 

Code Explanation 

3 Invalid request; function code out of range 

5 In XM, the status block address is not in valid user address 

space. 

Example: 

Refer to the example for the .MTATCH request. 

2.56 .MWAIT (FB and XM Only) 

This request is similar to the .WAIT request. .MWAIT, however, suspends 
execution of the job issuing the request until all messages sent to the other 
job or requested from the other job have been received. It should be used 
with the .RCVD or .SDAT modes of message handling, where no action is 
taken when a message is completed. 

Macro call: .MWAIT 

Request Format: 

RO = 



11 







Errors: 

None. 
Example: 



! + 

I .MWflIT - This is an example in the use of the .MWAIT request. 

f The example is actually two prosrramsi a BacK^round Job 

I which sends messages) and a Foreground Job i which receives them. 

i NOTE! Each prosfram should be assembled and linked separately. 





.TITLE 


MWfllTF.MftC 


i + 






i Fo re 9 round P ro s ram 






.MCALL 


.RCVD. .MWAIT, .PR 


MWfilTF: 


.RCMD 


«AREA ,»MBUFF.ttaO 




.PRINT 


nFGJOB 




.MWftIT 


• 




TBT 


MBUFF+2 




BEQ 


FEXIT 




.PRINT 


■ FMSG 




.PRINT 


•MBUFF+2 




BR 


MWfllTF 



iReiuest a messaSe up to 80 char. 
;No error possible - always a BG 



;Do some other processing 
illKe announcing FG active. 



iWait for message to arrive.. 

iNull messaSe? 

!Yes...exit the prosram 

iAnnounce we Sot the messase. 

iand echo it bacK 

iLoop to Set another one 
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iEx i t pro 9ram 
!EMT Argument Block 
iBuffer - M5S lenSth + 1 
iMaKe sure 80 char Message ends ASCIZ 
FG aliue and well and uaitinsi for a message!/ 
Got your message it reads:/ 



! + 

i Background Program - Send a 'null' message to stop both programs 



FEXIT: 


.EXIT 




AREA: 


.BLKM 


5 


MBUFFs 


.BLKW 


41 . 




.UORD 





FGJOB: 


.ASCIZ 


/Hi - FG a 


FMSG: 


.ASCIZ 


/Hey BG - 




.END 


MWAITF 




.TITLE 


MWAITB.MAC 



.MCALL 



.SDAT..MWAIT..GTLIN..EXIT,.PRINT 



MWAITB: 


CLR 


BUFF 




.GTLIN 


*BUFF,»PRDMT 




.SOAT 


»AREA.»BUFF.«aO. 




BCS 


1« 




.MWAIT 






TST 


BUFF 




BNE 


MMAITB 




.EXIT 




1«: 


PRINT 
.EXIT 


»NOFG 


AREA: 


.BLKM 


5 


BUFF: 


.BLKW 


no. 


PROMT! 


.ASCII 


/Enter message to 


NOFG: 


.ASCIZ 


/?No FG?/ 




.END 


MWAITB 



be 



iClear 1st uo rd 

iGet something to send to FG from TTY 
iSend input as message to FG 
iBranoh on error - No FG 
iWait for message to be sent 
iSent a null message? 
iNo>..loop to send another message. 
i Yes ...exit pro gram 
iNo FG ! 
iExi t prog ram 
lEMT Argument BlocK 
!Up to SO char message 
sent to FG JOb/< 15X 12>/>/<200> 
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The .PEEK programmed request returns in RO the contents of a memory 
location; .POKE changes the contents of a memory location. The .POKE 
request also returns the old contents of the memory location in RO to sim- 
plify the saving and restoring of a location. .PEEK and .POKE must be 
used in an XM environment to change memory locations that are not de- 
fined as monitor fixed offsets, and should be used with all RT-11 monitors 
for compatibility. 

Although .PEEK and .POKE may seem very similar to .GVAL and .PVAL, 
respectively, they are different in the way they refer to locations. .GVAL 
and .PVAL access only monitor fixed offsets. All offsets used by .GVAL and 
.PVAL are calculated relative to the base of the resident monitor. Ad- 
dresses used by .PEEK and .POKE, on the other hand, are simply memory 
addresses. Although .PEEK and .POKE can be used to access monitor fixed 
offsets, this requires that you find the base address of RMON, add the offset 
value, and use the resulting address as an argument to .PEEK or .POKE. 

Macro Calls: .PEEK area,address 



.POKE area, address,value 



where: 



area is the address of a two- or three- word EMT argument block 

address is the address of the location to examine or change 
value is the new contents to place in the location 
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Request Format for .PEEK 
RO -* area: 



34 



address 



Request Format for .POKE: 
RO -^ area: 



34 



address 



value 



Errors: 

None. 
Example: 

iExawple of .PEEK and .POKE prosramwed requests. 

JThis example illustrates a way of readinsr and aettinS 

ithe default file size used by the .ENTER pe<iuest. 

iNorwally. this would be done usinS the .GMAL and .PyflL proSramwed 

ireiuests. (Refer to the example Siuen for the . PVAL request.) This 

iexample computes the address of the word in RMON contalnini the 

idefault file size used by the .ENTER retuest and uses .POKE 

iboth to ohanse the default file size to 100. blocks and to return 

ithe old default file size in RO. 

i 

.MCALL .PEEK. .POKE. .EXIT 

RMaN= 54 
MAXBLK= 314 



START: 



.PEEK 

ADD 

MQV 

.POKE 

MOM 

.EXIT 



•EMTBLK ,»RMDN 

«MAXBLK . RO 

RO. Rl 

• EMTBLK I Rl . »NEWSIZ 

RO. OLDSIZ 



EMTBLK: 


.BLKW 


3 


NEMSIZi 


.NORD 


100. 


OLDSIZ: 


.WORD 






IPioK UP base of RMON from Ico. 54 
!Add fixed offset of default file size. 

iSet a neu default file size, return old 

idefault file size in RO and saue the old size. 

iUe'll Just exit nou. but presumably 

tin a real proslram we'd do more 

iprocessin^i perhaps creatine files 

iuilh the new default size we Just set. then 

ibefore exitinsl we'd restore the old 

idefault size. 

iEMT area 

iEMT area 

iThe old default size is saued here. 



.END 



START 



2.58 .POKE 

Refer to .PEEK/.POKE (Section 2.57). 

2.59 .PRINT 

The .PRINT request causes output to be printed at the console terminal. 
The string to be printed can be terminated with either a null (0) byte or a 
200 byte. If the null (ASCIZ) format is used, the output is automatically 
followed by a carriage return/line feed combination. If a 200 byte termi- 
nates the string, no carriage return/line feed combination is generated. 
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Control returns to the user program after all characters have been placed 
in the output buffer. 

When a foreground job is running and the job that is producing output 
changes, a B> or F> appears. Any text following the message has been 
printed by the job indicated (foreground or background) until another B> 
or F> is printed. 

When a system job prints a message to the terminal, the message is pre- 
ceded by logical-job-name. 

If the foreground job issues a message using .PRINT, the message is printed 
immediately, no matter what the state of the background job. Thus, for 
urgent messages, the .PRINT request should be used (rather than 
.TTYOUT or .TTOUTR). The .PRINT request forces a console switch and 
guarantees printing of the input line. If a background job is doing a prompt 
and has printed an asterisk but no carriage return/line feed combination, 
the console belongs to the background and .TTYOUTs from the foreground 
are not printed until a carriage return is typed to the background. A fore- 
ground job can force its message through by doing a .PRINT instead of the 
.TTYOUT. 

Macro Call: .PRINT addr 

where: 

addr is the address of the string to be printed 
Errors: 

None. 
Example: 

.TITLE PRINT. MAC 



.PRINT - This is an example in the use of the .PRINT request. 
The example merelv accepts input from the console terminal and 
echoes it bacK . 



START: 



1«: 

BUFF: 

PROMT: 



.MCALL 

.GTLIN 

TSTB 

BED 

.PRINT 

CLRB 

BR 

• EXIT 

.BLKM 

.ASCII 

.END 



.GTLINi. PRINT ..EXIT 

»BUFF>itPROMT iGct a line of input from Keyboard 

BUFF iNothina entered? 

1* iBranch if nothing entered 

•BUFF iEcho the input bacK 

BUFF iClear first char of buffer 

START iGo bacK for more 

lExit program on null input 
^1' !80 character buffer (ASCIZ for .PRINT) 

/Enter somet h in s/< i5>< 12>/ >/<200> 
START 



2.60 .PROTECT/.UNPROTECT (FB and XM Only) 

.PROTECT 

The .PROTECT request allows a job to obtain exclusive control of a vector 

(two words) in the region to 474. If the request is successful, it indicates 
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that the locations are not currently in use by another job or by the monitor. 
The job then can place an interrupt address and priority into the protected 
locations and begin using the associated device. 

Macro Call: .PROTECT area,addr 

where: 

area is the address of a two-word EMT argument block 

addr is the address of the word pair to be protected 

NOTE 

The argument addr must be a multiple of four, and must be 
less than or equal to 474(octal). The two words at addr and 
addr + 2 are protected. 

Request Format: 
RO — > area: 

Errors: 

Code Explanation 

Protect failure; locations already in use. 

1 Address {addr) is greater than 474 or is not a multiple of 4. 

Example: 

.TITLE PRDTEC.MAC 



31 







addr 



.PROTECT / .UNPROTECT - This is an example in the use of the .PROTECT 
and .UNPROTECT requests. The example illustrates how to protect the 
uectors of a device while an inline interrupt service routine does 
a data transfer (in this case the device is a DLll Serial Line Interface)i 
Nhen the program is finished) the vectors are unprotected for possible 
use by another Job. 



START! 



FINIi 
BUSY: 



AREA: 
LIST: 



.MCALL 
.DEVICE 



•PROTECT 
BCS 



JSR 



MORD 
MDRD 



.DEVICE.. EXIT (.PROTECT.. UNPROTECT.. PR I NT 
• AREA. "LIST 



• AREA .•300 
BUSY 



RS.DLU 



128. 
BUFFR 



UNPROTECT »AREA.«300 

EXIT 

PRINT •NOVEC 

EXIT 

BLKM 3 

WORD 17B500 

WORD 

WORD 



•Setup to disable DLll interrupts on 

l.EXIT or "C-C 

SProtect the DLll vectors 

{Branch if already protected 

■Set UP data to transmit over DLll 

iUse DLll xfer routine (see .INTEN 

iexaitipl e ) 

iArduments • . .Mo rd count 

IData buffer addr 

.Continue p races s in sr *. . 

;. I . eventual Iv to exit prosram 

.Print error messasre... 

! then exit 

iEMT Argument blocK 

iCSR of DLll 

iStuff it with '0' 

iList te rminato r 
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BUFFRi iData to send oyer DLll 

.REPT 8i iB lines of 32 characters... 

.ASCIZ /HeUo OLll... Are You There ??/ 

.ENOR 

NOVEC; .ASCIZ /?Veotor already protected?/ lError message text 

.END START 

.UNPROTECT 

The .UNPROTECT request is the complement of the .PROTECT request. It 
cancels any protected vectors in the to 476 area. An attempt to unprotect 
a vector that a job has not protected is ignored. 

Macro Call: .UNPROTECT area,addr 

where: 

area is the address of a two-word EMT argument block 

addr is the address of the protected vector pair that is going to be 
canceled. The argument addr must be a multiple of four, and 
must be less than or equal to 474(octal) 

Request Format: 



RO — > area: 



31 



addr 



Errors: 

Code Explanation 

1 Address {addr) is greater than 474(octal) or is not a multiple 

of four. 

Example: 

Refer to the example for the .PROTECT request. 



2.61 .PURGE 



The .PURGE request deactivates a channel without performing a 
.HRESET, .SRESET, .SAVESTATUS, or .CLOSE request. .PURGE frees a 
channel without taking any other action. If a tentative file has been en- 
tered on the channel, the file is discarded. An attempt to purge an inactive 
channel is ignored. 

NOTE 

Do not purge channel 17(octal) if your program is overlaid 
because overlays are read on that channel. 

Macro Call: .PURGE chan 
where: 

chan is the number of the channel to be freed 
Request Format: 



RO = 3 chan 
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Errors: 

None. 
Example: 



.TITLE 



PURGE. MAC 



i + 

i .PURGE - This is an example in the use of the PURGE re<iuest. 

; This example tnerSes 2-6 files into 1 fllei MaKin<l use of .SA'.'ESTATUS 

! and .REOPEN to read all input files on one channel. The .PURGE re>iuest 

) is used to free the input channel after each transfer. 



STARTi 



1«: 



lit: 
5*: 



6«: 



7*: 

AREA: 

BLKi 

MBLK: 

SAMBLK: 

DEFEXT: 

NOINP; 

UERR: 

RERRi 

DONEs 

BUFFR! 
DSPACE 



■MCALL 
.MCALL 
ERRBYT 

.CSIGEN 

MOW 

MOV 

MOV 

.SAVEST 

BCS 

ADD 

INC 

CMP 

BGE 

MOV 

BEQ 

.REOPEN 
CLR 

.READU 
BCC 
TSTB 
BNE 

.PURGE 
ADD 
TST 
BNE 

.CLOSE 

. PR I NT 

.EXIT 

.WRITW 

INC 

INC 

BCC 

MOV 

BR 

MOVE 

BR 

MOV 

.PRINT 

.EXIT 

.BLKN 

.UORD 

.MORD 

.BLKW 

.MDRD 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.EVEN 

.BLKM 



.END 



. CS I GEN i.SAVESTATUSi. REOPEN f. CLOSE.. EX IT 

. READM I .MRITU > . PRINT . . PURGE 

= 52 iError byte loo in SYSCOM 



• DSPACE, SDEFEXT 

xs.Ra 

•AREA.R3 

• SAVBLK ,R5 
R3,R4,R5 
Z« 
«12,R5 

Ra 

*8. iR4 

1$ 

• SAVBLK iR5 
7t 

R3 <«3 ,R5 

BLK 

R3,«3 .«BUFFR.«25B, 

6« 

@»ERRBYT 

B* 

• 3 

»12,R5 
@R5 

4$ 

»0 
ODONE 

R3 ."O (SBUFFR >«25B. 

UBLK 

BLK 

5* 

itMERR iRO 

g« 

«NQINP,RO 
S$ 

• RERR.RO 



5 





30. 

0(0.0.0 

/?No input files?/ 

/?Write Error?/ 

/?Read Error?/ 

/I-O Transfer CoMPleted/ 



SGet file spec .open files. load handlers 

iRfl = 1st input channel 

iR3 => EMT ArSument block 

iRS => Channel savestatus blocKs 

iSaue channel status 

{Branch if channel never opened 

SAdJust RS to point to next status blocK 

iBuMP R4 to = next input channel 

iDone all input channels? 

iBranch if not 

!R5 => to 1st saved channel status 

iBranch if no input files 

iRe-OPen input channel on Ch 3 

iStart reading uith blccK 
BLK iRead a blocK 

iBranch if no error 

iCheoK if error = EOF 

iBranch if not EOF 

iClear input channel for re-use 

SPoint R5 to next saued ch status 

iAny more input channels? 

iBranch if yes 

iUe're done. ..close output channel 

iAnnounoe werSe complete 

iExit program 
NBLK iMrite blocK Just read 

iBuwp to next output blocK 

isame for input blk (doesn't affect C bit) 

iBranch if no error on write 

iMrite error - RO => message 

ime r^e . . . 

iRO => No input files messase 

ime r<le . . . 

iRO => Read error Message 

iReport error 

ithen exit p ro^ram 

iEMT Argument blocK 

iCurrent read block 

iCurrent urite block 

iSaued channel status area 

iNo default extensions for CSIGEN 

iError messages 



25S. 



START 



i I/O buf f e r 
{Handlers start here. 



2.62 .PVAL 

See .GVAL/.PVAL (Section 2.37). 
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2.63 .QELDF (Device Handler Only) 

The .QELDF macro symbolically defines queue element offsets for the spec- 
ified set of system generation special features. The queue element offsets 
generated by this macro are as follows: 

Q.LINK = (Link to next queue element) 

Q.CSW = 2. (Pointer to channel status word) 

Q.BLKN = 4. (Physical block number) 

Q.FUNC = 6. (Special function code) 

Q.JNUM = 7. (Job number) 

Q.UNIT = 7. (Device unit number) 

Q.BUFF = 'OlO (User virtual memory buffer address) 

Q.WCNT = -012 (Word count) 

Q.COMP = "014 (Completion routine code) 

Since the handler usually deals with queue element offsets relative to 
Q.BLKN, the .QELDF macro also defines the following symbolic offsets: 

Q$LINK=-4 
Q$CSW=-2 
Q$BLKN = 
Q$FUNC = 2 
Q$JNUM = 3 
Q$UNIT = 3 
Q$BUFF=4 
Q$WCNT=6 
Q$COMP=-O10 

For SJ and FB systems: 

Q.ELGH = '016 (End of queue element; used to find length) 

For XM systems: 

Q.PAR = -016 (PARI relocation bias) 

Q$PAR = -012 

Q.ELGH = '024 (End of queue element; used to find length) 

Example: 

Refer to the example following the description of .DRAST. 



2.64 .QSET 



The .QSET request allows additional entries to be made to the RT-11 I/O 
queue. A general rule to follow is that each program should contain one 
more queue element than the total number of I/O requests that will be 
active simultaneously on different channels. Timing and message requests 
such as .MRKT, .TWAIT, .SDAT/C, and .RCVD/C also require queue ele- 
ments and must be considered when allocating queue elements for a pro- 
gram. Note that if synchronous I/O is done (such as .READW/.WRITW) and 
no timing requests are done, no additional queue elements need be allo- 
cated. 
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Each time .QSET is called, a specified contiguous area of memory is divided 
into seven- word segments (10- word [decimal] segments for the XM monitor) 
and is added to the queue for that job. .QSET can be called as many times 
as required. The queue set up by multiple .QSET requests is a linked list. 
Thus, .QSET need not be called with strictly contiguous arguments. The 
space used for the new elements is allocated from your program space. Care 
must be taken so that the program in no way alters the elements once they 
are set up. The .SRESET and .HRESET requests discard all user-defined 
queue elements; therefore any previous .QSET requests must be reissued. 
However, you must not specify the same space in two separate .QSET re- 
quests if there has been no intervening .SRESET or .HRESET request. 

Care should also be taken to allocate sufficient memory for the number of 
queue elements requested. The elements in the queue are altered asynchro- 
nously by the monitor; if enough space is not allocated, destructive refer- 
ences occur in an unexpected area of memory. The monitor returns the 
address of the first unused word beyond the queue elements. Other restric- 
tions on the placement of queue elements are that the USR must not swap 
over them and they must not be in an overlay region. For jobs that run 
under the XM monitor, queue elements must be allocated in the lower 28K 
words of memory, since they must be accessible in kernel mapping. In 
addition, the elements must not be in the virtual address space mapped by 
kernel PARI, specifically the area from 20000 to 37776(octal). 

NOTE 

Programs that are to run in XM as well as SJ or FB environ- 
ments should allocate lO(decimal) words for each queue ele- 
ment. Alternatively, a program can specify the start of a 
large area and use the returned value in RO as the top of the 
queue element. 

The following programmed requests require queue elements: 



.TWAIT 


.RCVDW 


.MRKT 


.WRITE 


.READ 


.WRITC 


.READC 


.WRITW 


.READW 


.SDAT 


.RCVD 


.SDATC 


.RCVDC 


.SDATW 


) Call: .QSET addr,len 



where: 

addr is the address at which the new elements are to start 

len is the number of entries to be added. In the SJ and FB moni- 
tor, each queue entry is seven words long; hence the space set 
aside for the queue should be Zen*7 words. In the XM monitor, 
lO(decimal) words per queue element are required 

On completion, RO contains the address of the first word beyond the allo- 
cated queue elements. 
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Errors: 

In an extended memory environment, an attempt to violate the PARI 
restriction results in a ?MON-F-addr error, which can be intercepted 
with a .SERR programmed request. 

Example: 

.TITLE OSET.MftC 
i + 

i .OSET - This is an example in the use of the .OSET request. 
i The example illustrates a user implemented "Timed Read" to oancel an 
i input request after a specified time interual. 



.MCflLL 



. MRKT ..TTINR..EXIT..PRINT , , TTYOUT . . CMKT .. THAI T .. OSET 



LF = 12 
JSW = 4a 
TCBIT* = 100 
iReturn C-bit bit in JSU 
TTSPC$ = 10000 



iLine Feed 

iJob Status Mord location 



;TTY Special Mode bit in JBW 



START; 


.OSET 


•XOUE. HI 




iNeed an extra 0-Elem for this 


1»: 


MOV 


• PROMT ,R0 




iMainline - RO => Prompt 




MOV 


■ BUFFR. Rl 




iRl = > Input buffer 




CALL 


TREAD* 




iDo a "timed read" 




BCS 


Z* 




iC-bit set = Timed out 




.PRINT 


• LINE 




i "Process" data... 




BR 


1* 




iGo back for more 


Z«; 


.PRINT 
.EXIT 


•TIMOUT 




iRead timed out - could process 
{partial data but ue'll Just exit 




i» TREAD* 


- "Timed Read" 


Subroutine * 




i « Input: 


RO => Prompt 


St Tins / 


RO = if no prompt « 




;« 


Rl => Input 


Buffer 


« 




i* Output : 


Buffer contains input 


chars, if any. terminated « 




i* 


by a null ch 


ar. C-Bit 


set if timed out * 


TREAD*] 


TST 


RO 




iSee if ue have to prompt 




BEO 


1* 




.Branch if no . . . 




.PRINT 






Output prompt 


1«; 


CLR 


TBYT 




Clear t ime-out f las 




.MRKT 


•TAREAtSTIME , 


• TOUT ,ni 


Issue a .MRKT for 10 sec 




BIS 


•TCBIT*.@«JSW 




Set C-Bit bit in JSW (for F/B) 




CLRB 


SRI 




Start with "empty" buffer 


TTIN: 


.TWAIT 
.TTINR 


• AREA 




Wait so we don't lock out BG 
Look for a character 




BIT 


• 1 ,(PC) + 




Timed out? 


TBYT: 


.WORD 







Time-out flai 




BNE 


Zt 




Branch if yes 




BCS 


TTIN 




Branch if input not complete 




MOVB 


R0.(R1)+ 




Xf e r 1st characte r 




.CMKT 


• TAREA ."O 




Cancel .MRKT 


Z«s 


BIS 


«TTSPC».e«JSW 




Turn on TTs Special mode 


3$: 


.TTINR 






Flush TT; rinS buffer 




MOVB 


R0,(R1) + 




puttinsf characters in user buffer 




BCC 


3* 




If more char, io net 'em 




CLRB 


-(Rl ) 




Terminate input with null byte 




BIC 


•TCBIT*!TTSPC».@»JSW 


Clear bits in JSW 




ROR 


TBYT 




Set carry if timed out 




RETURN 






Return to caller 


TOUT: 


INC 
RETURN 


TBYT 




Leave completion code 


XOUE: 


.BLKM 


10. 




Extra 0-Element 


AREA: 


.WORD 


O.WAIT 




EMT Arsument block for .TWAIT 


TAREA; 


.SLKW 


a 




EMT Arsument block for .MRKT 


TIME: 


.WORD 


0.600. 




Time-out interual (10 sec) 


MAIT: 


.WORD 


0.1 




1/GO sec wait between .TTINRs 


LINE: 


.ASCII 


/Not in stock 


- Part « 


/ iDummy response 


BUFFR: 


.BLKB 


81. 




User input buffer 


PROMT: 


.ASCIZ 


/Enter Part • 


>/<200> 


Prompt 


TIMOUT; 


.ASCIZ 


/Timed read expired!/ 


Too bad me ssasre 




.END 


START 
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2.65 .RCTRLO 



The .RCTRLO request makes sure that the console terminal is able to print 
by resetting the CTRL/0 switch for the terminal. A CTRL/0 typed while 
output is directed to the console terminal inhibits the output from printing 
until either another CTRL/0 is struck or the program resets the CTRL/0 
switch. Therefore, a program with a message that must appear at the con- 
sole should reset the CTRL/0 switch. 

A program should also issue a .RCTRLO request whenever it changes the 
contents of the job status word (JSW). Issuing a .RCTRLO request updates 
the monitor's internal status information to reflect the current contents of 
the JSW. 

Macro Call: .RCTRLO 

Errors: 

None. 

Example: 



.TITLE RCTRLO. MAC 
y 
• RCTRLO - This is an example in the use of the .RCTRLO reiuest. 
In this examplet the user prasram first calls the CSI in General mode > 
then processes the coinmandi When finished) it returns to the CSI for 
another comiriand line. To niaKe sure that the proniptina '*' typed by 
the CSI is not inhibited by a CTRL-0 in effect from the last operation) 
terminal output is assured uia the iRCTRLO request prior to the 
CSI call. 



•MCALL 



.RCTRLO). CSIGEN). EXIT 



START: 



DEXT: 
DSPACE: 



.RCTRLO 
.CSIGEN 



JMP 
.UORD 



«DSPACE)«OEKT )«0 



START 
0)0)0)0 



iMake sure TTj output is enabled 
ilssue a .CSIGEN request to «et 
icommand 

i(CSI will prompt with '♦') 
Process the command... 



!Get another command... 

iNo default extensions 

iSpace for handlers starts here 



.END 



START 



2.66 .RCVD/.RCVDC/.RCVDW (FB and XM Only) 

The .RCVD (receive data) request allows a job to read messages or data 
sent by another job in an FB environment. 

There are three forms of the .RCVD request, and they are used with the 
.SDAT (send data) request. The send data-receive data request combination 
provides a general data/message transfer system for communication be- 
tween a foreground and a background job. .RCVD requests can be thought 
of as .READ requests where data transfer is not from a peripheral device 
but from the other job in the system. Additional queue elements should be 
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allocated for buffered I/O operations in .RCVD and .RCVDC requests (see 
the .QSET request). Under an FB monitor with the system job feature, 
.RCVD/C/W requests and .SDAT/C/W requests remain valid for sending 
messages between background and foreground jobs in addition to the gen- 
eral read and write capability available to all jobs. 

Be particularly careful if you use both synchronous (.RCVDW and 
.SDATW) and asynchronous (.RCVDC and .SDATC) requests in the same 
program. If you issue a mainline .SDATW while there is a pending 
.RCVDC, the .SDATW will wait until the .RCVDC is satisfied. If the com- 
pletion routine for the .RCVDC issues another .RCVDC, the mainline 
.SDATW will never complete. In general, you should avoid the use of both 
synchronous and asynchronous message requests in the same program. 

.RCVD 

This request is used to receive data and continue execution. The request is 

posted and the issuing job continues execution. When the job needs to have 

the transmitted message, an .MWAIT should be executed. This causes the 

job to be suspended until all .SDATx and .RCVDx requests for the job are 

complete. 

Macro Call: .RCVD area,buf,wcnt 



where: 



area is the address of a five-word EMT argument block 

buf is the address of the buffer into which the message 
length/message data is to be placed 

went is the number of words to be transferred 

Request Format: 

RO —* area: 



26 



reserved 



buf 



went 



Upon completion of the .RCVD, the first word of the message buffer con- 
tains the number of words transmitted. Thus, the space allocated for the 
message should always be at least one word larger than the actual message 
size expected. If the sending job attempts to send more words than the 
receiver specified in the went argument of the .RCVD request, the first 
word of the buffer will contain the number of words that the sender speci- 
fied, but only went words will be actually transferred. The rest of the 
sender's message will be ignored. 

The word count is a variable number, and as such, the .SDAT/.RCVD com- 
bination can be used to transmit a few words or entire buffers. The .RCVD 
operation is only complete when a .SDAT is issued from the other job. 

Programs using .RCVD/.SDAT must be carefully designed to either always 
transmit/receive data in a fixed format or to have the capability of handling 
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variable formats. Messages are all processed in first-in first-out order. 
Thus, the receiver must be certain it is receiving the message it actually 
wants. Message handling in the FB monitor does not check for a word count 
of zero before queuing a send or receive data request. Since RT-11 distin- 
guishes a send from a receive by complementing the word count, a .SDAT of 
zero words is treated as a .RC VD of zero words. Avoid a word count of zero 
at all times when using a .RCVD request. 

Errors: 

Code Explanation 

No other job exists in the system. (A job exists as long as it is 
loaded, whether or not it is active.) 

Example: 

Refer to the example for the .SDAT request. 

.RCVDC 

The .RCVDC request receives data and enters a completion routine when 
the message is received. The .RCVDC request is posted and the issuing job 
continues to execute. When the other job sends a message, the completion 
routine specified is entered. 

Macro Call: .RCVDC area,buf,wcnt,crtn 

where: 

is the address of a five-word EMT argument block 



area 
buf 

went 
crtn 



is the address of the buffer into which the message 
length/message data is to be placed 

is the number of words to be transmitted 

is the address of a completion routine to be entered 



As in the .RCVD request, word of the buffer contains the number of words 
transmitted when the transfer is complete. 

Request Format: 

RO — * area: 



26 







reserved 



buf 



went 



crtn 



Errors: 



Code Explanation 

No other job exists in the system. (A job exists as long as it is 
loaded, whether or not it is active.) 
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Example: 



.TITLE RCVDC.MflC 

) + 

! .RCVDC - This Is an sxample of the .RCVDC request. The example 

i is a sinulation of a mainline Foreground program which is currently 

i suspended uaitins for a message from the BacKaroundi but which needs 

! tc close a file (perhaps opened by a .ENTER ?) before aborting from 

i CTRL-C action. A coinpletion routine periodically inspects the CTRL-C 

I status word and resumes the mainline if double CTRL-C is entered. 

i NOTE: This example MUST be run as a FG Job under an FB monitor. 

)- 



.MCALL 
.MCALL 



.SCCfli.RCyDC.EXIT .. PRINT i .MRKT 
.OSETi.SFNDi.RSUh 



START! .OSET nOELEM.*! 

.SCCA «MAREAi*SCCA 

It! CALL CMATCH 

.RCVDC «MAREA.»MBUFF.»aO. i»MESG 



iAllocate another 0-Element 
{Inhibit *C*C action by monitor 
iStart "watchdog" completion rtne 
iLqoK for a messaile 
iNo errors - there's always BG 
iOther processing here... 





.PRINT 


•SLEEP 




.SPND 






TST 


SCCA 




BNE 
: 


CLOSE 




1 » 

i <process message here> 

1 




1 

BR 


1« 


CWATCHi 


TST 


SCCA 




BEO 


MARK 


MESG! 


RETURN 


.RSUM 


MARK: 


.MRKT 
RETURN 


• CAREA.«TIME.»C 



lAnnounoe we're sroinif to suspend 
iSuspend to wait for message 
iWe'we been .RSUMed . . . 'C'C hit?? 
{Branch if yes 
■otherwise assume messale came in. 



iLoop. . . 

iChecK if *C'C entered... 

iB ranch if no 

lYes.i.waKe up the mainline 

ithen leave completion code 

iSchedule to run as(ain in 10 sec. 

ithen leaue completion code 



CLOSE: 



OELEM! 

MBUFF! 

MAREA! 

CAREA! 

TIME! 

SCCA: 

ABORT: 
SLEEP: 



PRINT "ABORT 

<Output file(5) closed here> 
EXIT 



BLKM 
BLKM 
BLKW 
BLKM 
UORD 
WORD 

A5CIZ 
ASCIZ 



7 

dl. 

5 

a 

O.BOO. 




•Announce we're aborting 
{proceed with "orderly" abort 



iExit the proiTram 

iExtra 0-Element 

iMessa^e buffer 

iEMT Argument blocks 

I 

iTime out in 10 seconds 

i~C*C Status word 



/?! Abort AcKnowledSed. . .ClosinS Output File(s) I?/ 
/! Mainline Suspending !/ 



.END 



START 



.RCVDW 

.RCVDW is used to receive data and wait. A message request is posted and 
the job issuing the request is suspended until all pending .SDATx and 
.RCVDx requests for the job are complete. When the issuing job runs again, 
the message has been received, and word of the buffer indicates the num- 
ber of words transmitted. 

Macro Call: .RCVDW area,buf,wcnt 
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where: 



area 
buf 



is the address of a five-word EMT argument block 

is the address of the buffer into which the message 
length/message data is to be placed 



went is the number of words to be transmitted 
Request Format: 
RO -^ area: 



26 







reserved 



buf 



went 







Errors: 

Code 





Explanation 

No other job exists in the system. (A job exists as long as it is 
loaded, whether or not it is active.) 



Example: 

Refer to the example for the .SDATW request. 



2.67 .RDBBK (XM Only) 



The .RDBBK macro defines symbols for the region definition block and 
reserves space for it. The .RDBBK automatically invokes .RDBDF. 

Macro Call: .RDBBK rgsiz 

where: 

rgsiz is the size of the dynamic region needed (expressed in 32- 
word units) 

Example: 

See Chapter 4 of the RT-11 Software Support Manual for an example 
that uses the .RDBBK macro and a detailed description of the ex- 
tended memory feature. 



2.68 .RDBDF (XM Only) 



The .RDBDF macro defines the symbolic offset names for the region defini- 
tion block and the names for the region status word bit patterns. In addi- 
tion, this macro also defines the length of the region definition block by 
setting up the following symbol: 

R.GLGH = 6 
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The .RDBDF macro does not reserve space for the region definition block. 

Macro Call: .RDBDF 

The .RDBDF macro expands as follows; 



R.GID 


= 


R.GSIZ 


= 2 


R.GSTS 


= 4 


R.GLGH 


= 6 


RS.CRR 


= 100000 


RS.UNM 


= 40000 


RS.NAL 


= 20000 



2.69 .READ/.READC/.READW 



Read operations for the three modes of RT-11 I/O are done using the 
.READ, .READC, and READW programmed requests. 

In the case of .READ and .READC, additional queue elements should be 
allocated for buffered I/O operations (see the .QSET request). 

Upon return from any .READ, .READC, or .READW programmed request, 
RO contains the number of words requested if the read is from a sequential- 
access device (for example, paper tape). If the read is from a random-access 
device (disk or DECtape), RO contains the actual number of words that will 
be read (.READ or .READC) or have been read (.READW). This number is 
less than the requested word count if an attempt is made to read past end- 
of-file, but a partial transfer of one or more blocks is possible. In the case of 
a partial transfer, no error is indicated if a read request is shortened. 
Therefore, a program should always use the returned word count as the 
number of words available. 

For example, suppose a file is five blocks long (it has block numbers to 4) 
and a request is issued to read 512(decimal) words, starting at block 4. 
Since 512 words is two blocks, and block 4 is the last block of the file, this is 
an attempt to read past end-of-file. The monitor detects this and shortens 
the request to 256(decimal) words. On return from the request, RO contains 
256, indicating that a partial transfer occurred. Also, since the request is 
shortened to an exact number of blocks, a request for 256 words either 
succeeds or fails, but cannot be shortened. 

An error is reported if a read is attempted starting with a block number 
that is beyond the end-of-file. The carry bit is set, and error code appears 
in byte 52. No data is transferred in this case, and RO contains a zero. 

.READ 

The .READ request transfers to memory a specified number of words from 
the device associated with the specified channel. The channel is associated 
with the device when a .LOOKUP or .ENTER request is executed. Control 
returns to the user program immediately after the .READ is initiated, pos- 
sibly before the transfer is completed. No special action is taken by the 
monitor when the transfer is completed. 
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Macro Call: .READ area,chan,buf,wcnt,blk 

where: 

area is the address of a five-word EMT argument block 

chan is a channel number in the range 0-376(octal) 

buf is the address of the buffer to receive the data read 

went is the number of words to be read 

blk is the block number to be read. For a file-structured 
.LOOKUP, the block number is relative to the start of the 
file. For a non-file-structured .LOOKUP, the block number is 
the absolute block number on the device. Note that the first 
block of a file or device is block number 0. The user program 
normally updates hlk before it is used again. If input is from 
TT: and blk - 0, TT: issues an uparrow C) prompt (This is true 
for all .READ requests.) 

Notes: 

1. .READ and .RE ADC requests instruct the monitor to do a read from the 
device by queuing a request for the device and immediately returning 
control to your program. 

2. .READ and .READC requests execute as soon as all previous I/O re- 
quests to the device handlers have been completed. Note that a read 
from RKl: must wait for a previous read from RKO: to complete. This is 
a hardware restriction common to most disks because the controller 
looks at all I/O operations sequentially. 

3. Read errors are returned from the .READ and .READC or the .WAIT 
request. Errors can occur on the read or on the wait, but only one error 
is returned. Therefore, the program must check for an error when the 
read is complete (.READ/BCS) and after the wait (.WAIT/BCS). The 
wait request returns an error, but it does not indicate which read 
caused the error. 

Errors reported on the return from the read request are as follows: 

a. Nonexistent device/unit 

b. Nonexistent block 

c. In general, errors that do not require data transfers but are control- 
ler errors or EOF errors 

4. During the .READ and .READC requests, the monitor keeps track of 
errors in the channel status word. If an error occurs before the monitor 
can return to the caller, the error is reported on the return from the 
read request with the carry bit set and the error value in RO. If the 
error occurs after return from the read request, the error is reported on 
return from the next .WAIT, or the next .READ/.READC. Some errors 
can be returned from .READ/.READC requests immediately, before any 
I/O operation takes place. One condition that causes an immediate er- 
ror return is an attempt to read beyond end-of-file. 
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5. If .READ/C/W requests are used to receive messages under a system job 
monitor, the buffer must be one word longer than the number of words 
expected to be read. Upon completion of the data transfer, the first word 
of the buffer will contain a value equal to the number of words actually 
transferred (as for .RCVD/C/W). 

Request Format: 

RO -^ area: 



10 chan 



blk 



buf 



went 



When the user program needs to access the data read on the specified 
channel, a .WAIT request should be issued as a check that the data has 
been read completely. If an error occurred during the transfer, the .WAIT 
request indicates the error. 



Errors: 



Code Explanation 

Attempt to read past end-of-file. 

1 Hard error occurred on channel. 



Channel is not open. 



Example: 



.TITLE READ. MAC 



•READ / .WRITE - This is an example in the use of the .READ / .WRITE 
requests. The example demonstrates asynchronous I/Q where a mainline 
prodram initiates input Mia .READ requests) does some other processins 
maKes sure input has completed uia the .WAIT request i then outputs 
the blccK Just read. Another .WAIT is issued before the next read 
is issued to maKe sure the previous write has finished. This example 
is another single file copf prosrami utilizing .C8IGEN to input the 
file specsi load the required handlers and open the files. 



WAIT..SRESET 



START: 



1$: 



Z«] 



.MCALL 


. READ.. WRITE. .C 


.MCALL 


.CSIGEN. .EXIT.. 


ERRBYT 


= 52 


.ENABL 


LSB 


.CSIGEN 


«DSPACE.«DEFEXT 


Moy 


•AREA.R5 


CLR 


IDBLK 


.READ 


R5.«3 


BCS 


S« 


i 

BIT 


• 1 iIOBLK 


BNE 


Z« 


.PRINT 
* 


•MESSG 


1 

.WAIT 


• 3 


BCS 


5» 


.WRITE 


R5.«0 


BCS 


3* 


INC 
i 


lOBLK 


1 

.WAIT 


• 


BCC 


It 



Error Byte location in SYSCOM 

Enable local symbol block 

Use CSIGEN to ^et handlers, files 

R5 => EMT Argument list 

Start reads with BlocK *0 

Read a blocK... 

Branch on error 

Then s imulate 

some other 

meaningful (?) 

process .. . 

Did read finish OK? 

Branch if not (must be hard error!) 

Now write the block Just read 

Branch on error 

Bump Block * 

Me could do some mere processlnsf here 

Wait for write to finish 
Branch if write was successful 
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3»! MOV «WERR)RO iRO => Write error msS 

4$; .PRINT iReport error 

BR 7* iMerSe to exit prosram 

5ti MOy "RERRiRO iRO => Read error iiissr 

BR 4* iBranoh to report error 

B»: TSTB S»ERRBYT iRead error. ..EOF? 

BNE 5t iBranoh if not ' 

.PRINT »DONE i Yes ... announce completion 

.CLOSE «0 iMaKe output file permanent 

7«: .SRESET iOismiss fetched handlers 

.EXIT ithen eKit program 

AREA:: .UORD iEMT Area blocK 

lOBLK: .WORD iBlDoK »t 

.WORD BUFF iBuffer addr 8. word count 

.WORD 256. ialready fixed in block... 

.WORD i 

BUFF: .BLKW 256. iI/0 buffer 

DEFEXT: .WORD tO lO lO iNo default extensions for CSIGEN 

DONE: .ASCIZ /I-O Transfer Complete/ iMes sasies . . . 

MESSG: .flSCIZ <15><12>/< SimulatinS Mainline Prooessina >/ 

WERRs .ASCIZ /?Write Error?/ 

RERR: .ASCIZ /?Read Error?/ 

.EVEN 

DSPACE: = • iHandlers may be loaded startins here 

.END START 

.READC 

The .READC request transfers a specified number of words from the indi- 
cated channel to memory. Control returns to the user program immediately 
after the .READC is initiated. Attempting to read past end-of-file also 
causes an immediate return, in this case with the carry bit set and the error 
byte set to 0. Execution of the user program continues until the .READC is 
complete, then control passes to the routine specified in the request. When 
an RTS PC is executed in the completion routine, control returns to the 
user program. 

Macro Call: .READC area,chan,buf,wcnt,crtn,blk 

where: 

area is the address of a five-word EMT argument block 

chan is a channel number in the range 0-376(octal) 

buf is the address of the buffer to receive the data read 

went is the number of words to be read 

crtn is the address of the user's completion routine. The address of 
the completion routine must be above 500(octal) 

blk is the block number to be read. For a file-structured 
.LOOKUP, the block number is relative to the start of the 
file. For a non-file-structured .LOOKUP, the block number is 
the absolute block number on the device. The user program 
normally updates blk before it is used again 

When a completion routine is called, error or end-of-file information for a 
channel is not cleared. The next .WAIT or .READ/.READC on the channel 
(from either mainline code or a completion routine) produces an immediate 
return with the C bit set and the error code in byte 52. The completion 
routine will never be entered if the .READC request returns an error. 
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Request Format: 
RO —> area: 



10 chan 



blk 



buf 



went 



crtn 



When a .READC completion routine is entered, the following conditions are 
true: 

1. RO contains the contents of the channel status word for the opera- 
tion. If bit of RO is set, a hardware error occurred during the 
transfer; consequently, the data may not be reliable. The end-of- 
file bit, bit 13, may be set. 

2. Rl contains the channel number of the operation. This is useful 
when the same completion routine is to be used for transfers on 
different channels. 

3. On a file-structured transfer, a shortened read is reported when 
the .READC request is returned, not when the completion routine 
is called. 

4. Registers RO and Rl can be used by the routine, but all other 
registers must be saved and restored. Data cannot be passed be- 
tween the main program and completion routines in any register 
or on the stack. 

Errors: 

Code Explanation 

Attempt to read past end-of-file; no data was read. 

1 Hard error occurred on channel. 

2 Channel is not open. 
Example: 



.TITLE 



READC. MAC 



.READC / .WRITC - This is an example in the use of the .READC / .WRITC 
requests. The example demonstrates euent-driuen I/O where a mainline 
prosram initiates a file transfer and completion routines continue it 
while the mainline proceeds with other processes. The example is another 
sinile file copy proiramt utilizinS .CSIGEN to input the file specsi load 
the required handlers and open the files. 



START: 



.MCALL 



, RE ADC. WRITC ..CLOSE ..PRINT . . CSI GEN , . EXI T ..WAIT ..SRESET 
iError Byte location in SYBCOM 

iUse CBIGEN to Set handlers, files 

iStart I/O 

iNow simulate other mainline process 



ERR5YT 


= 52 


.ENABL 


LSB 


.CSIGEN 


«DSPACE.»tDEFEXT 


CALL 


lOXFER 


.PRINT 


•MESBG 


Moy 


«-l .R5 
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1«; 


DEC 


R5 




BNE 


U 




TSTB 


EOF 




BEO 


1$ 




INCB 


EOF 




BEQ 


WERR 




BLT 


RERR 




.CLOSE 


• 




Moy 


ODONE.RO 




BR 


GBYE 


WERR: 


nog 


•WRERR. RO 




BR 


GBYE 


RERR: 


MOV 


•RDERR.RO 


GBYE: 


.PRINT 
.SREBET 
• EXIT 




NRDQNE: 


.WAIT 


«0 




BCS 


3* 


lOXFER: 


.READC 


»AREA («3 » I .»4$ 




BCC 


7* 




TSTB 


e»ERRBYT 




BEO 


6$ 


2*; 


DECB 


EOF 


3*; 


DECB 
RETURN 


EOF 


a*: 


.WAIT 


»3 




BCS 


2* 




.WRITC 


«AREA.«tO. . .«WRDONE 




BCS 


3* 


5*: 


INC 
RETURN 


BLOK 


6»: 


INCB 


EOF 


7*: 


RETURN 




AREA: I 


.WORD 





BLOK: 


.WORD 







.WORD 


BUFF 




.WORD 


256. 




.WORD 





BUFF: 


.BLKW 


258. 


DEFEXT: 


.WORD 


»0 lO (0 


DONE; 


•ASCIZ 


/I-O Transfer Camp 


MESSG: 


.ASCIZ 


/< Simulatinsf Main 


WRERR: 


.ASCIZ 


/?Wrxte Error?/ 


ROERR: 


.ASCIZ 


/?RGad Error?/ 


EOF: 


.BYTE 
.EVEN 





DSPACE 


= , 





i (Kill some t ime ) 

1 

iDid I/O complete? 

iNo...do some more mainline work 

iCheoK for read/write error 

iEOF = = Write error 

iEOF < = Read error 

iEDF > = End of File 

iRO => We're done messs 

iMerSe to exit proSram 

iSet UP error messases here... 



iPrint message 

iDismiss fetched handlers 

iExi t pro Sram 

(Write oompl rtne . . . w ri te successful? 

iB ranch if no t . . . 

iOueue UP a read 

iB ranch if oK . . . 

iError - is it EOF? 

iB rano h if yes 

iUser EOF FlaS to indicate hard error 

iEOF = -2 Read err / = -1 Write err 

iLeaue completion code 

iCompl rtne *2 - was read oK? 

iB ranch if not 

iQueue up a write .. . 

iB ranch if error 

iBump blooK » for 

iLeawe Completion 

iSet EOF flaS 

i then return 

iEMT Area block 

iBlock «t 

iBuffer addr & word count 

ialready fixed in block... 

iCompletion rtne addr 

i I/O buffer 

iNo default extensions for CSIGEN 



next read 
code . . < 



ete/ iMessaates... 
ine ProoessinS >/ 

iEOF flas 

iHandlers may be loaded startins here 



.END 



START 



.READW 

The .READW request transfers a specified number of words from the indi- 
cated channel to memory. When the .READW is complete or an error is 
detected, control returns to the user program. 

Macro Call: .READW area,chan,buf,wcnt,blk 

where: 

area is the address of a five-word EMT argument block 

chan is a channel number in the range 0-376(octal) 

buf is the address of the buffer to receive the data read 
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went is the number of words to be read; each .READ request can 
transfer a maximum of 32K words 

blk is the block number to be read. For a file-structured 
.LOOKUP, the block number is relative to the start of the 
file. For a non-file-structured .LOOKUP, the block number is 
the absolute block number on the device. The user program 
normally updates blk before it is used again 



Request Format 
RO 



area: 


10 1 chan 




blk 




buf 




went 








If no error occurred, the data is in memory at the specified address. In an 
FB environment, the other job can be run while the issuing job is waiting 
for the I/O to complete. 

If a volume is opened with a non-file-structured lookup and the word count 
specified is greater than the number of words left on the volume, .READW 
returns a hard error. 

Errors: 

Code Explanation 

Attempt to read past end-of-file. 

1 Hard error occurred on channel. 

2 Channel is not open. 
Example: 



.TITLE READW. MAC 

.READW / .WRITW - This is an example in the use of the .READW / .WRITW 
requests. The example is a sinSle file copy proSram. The file specs 
are input from the console terminalt and the input & Gutput files opened 
uia the general mode of the CSI. The file is copied usinit synchronous 
I/Oi and the output file is made permanent uia the .CLOSE request. 



START: 



READ: 



.MCALL 



1»: 



.CSI GEN.. READW. .PR I NT.. EX IT.. WRITW ..CLOSE i.SRESET 



iError Byte Location 

iGet strinS from terminal 

ilnput blocK * starts with 

>R5 => EMT Arsument list 

!Read a blocK on Channel 3 

iBlK»i Buff addr t, WC already 

iblK ! 

!B ranch if no errors 

, 1 5 error EOF? 

iVes. . . 

iRO => Read Error MessaSe 

iPrint the message 

;Ex i t pros ram 



ERRBYT=52 




.CSIGEN 


t>DSPACE.«DEXT 


CLR 


lOBLK 


Moy 


• AREA.R5 


.READW 


R5.»3 


BCC 


Zt 


TSTB 


B»ERRBYT 


BEO 


3* 


Moy 


MRERR.RO 


.PRINT 




BR 


at 



in a rsl 
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2$: 



3$: 



at: 



DEXT: 
AREA: 
IDBLK: 



BUFFR: 
RERR: 
MERR: 
DONE: 



DSPfiCE: 



•WRITW 

INC 

BCC 

MOy 

BR 

.CLOSE 

.PRINT 

.SRESET 

.EXIT 

.NORD 

.MORD 

.WORD 

.WORD 

.WORD 

.HARD 

.BLKN 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.EVEN 



.END 



R5 )»0 

lOBLK 

READ 

•tWERRiRO 

1« 

«0 

ODONE 



iNrite the blocK Just read 

iBuiiiP block « (doesn't affect C bit) 

i Bran oh if no error 

iRO => Write error message 

iBranch to output the messa9e 

iEnd-of -Fi 1 e . . .CI ose output ohannel 

lAnnounce successful copy 

iRelease hairidler(s) from mentory 

!Ex i t the p ros ram 



(0 (0 lO 





BUFFR 

256. 



256. 

/? Read error ?/ 

/? Write error ?/ 

/I-O Transfer Complete/ 



;No default extensions 

iEMT Arsument block 

iBlock * 

i I/O Buffer add r 

iWo rd Count 

i I/O Buf f e r 



SHandler(s) can be loaded starting 
i he re 



START 



2.70 .RELEAS 

See .FETCH/.RELEAS (Section 2.30). 

2.71 .RENAME 

The .RENAME request changes the name of the file specified. 

Macro Call: .RENAME area,Ghan,dblk 

where: 

area is the address of a two-word EMT argument block 

cchan is an unused channel number in the range 0-376(octal) 

dblk is the address of a block that specifies the file to be renamed 
followed by the new file name 

Request Format: 
RO -^ area: 



chan 



dblk 



The dblk argument consists of two consecutive Radix-50 device and file 
specifications. For example: 



DBLKi 



.RENAME 


"AREA »«7 .«DBLK 


iUSE CHANNEL 7 


BCS 


RNMERR 


!NOT FOUND 


,RAD50 


/DT3/ 




.RAD50 


/OLDFIL/ 




.RAD50 


/MAC/ 




.RAD50 


/DT3/ 




.RAD50 


/NEWFIL/ 




.RAD50 


/MAC/ 
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The first string represents the file to be renamed and the device where it is 
stored. The second represents the new file name. If a file with the same 
name as the new file name specified already exists on the indicated device, 
it is deleted. The second occurrence of the device name DT3 is necessary for 
proper operation and should not be omitted. The specified channel is left 
inactive when the .RENAME is complete. .RENAME requires that the han- 
dler to be used be resident at the time the .RENAME request is made. If it 
is not, a monitor error occurs. Note that .RENAME is legal only on files on 
block-replaceable devices (disks and DECtape). In magtape operations, the 
handler returns an illegal operation code in byte 52 if a .RENAME request 
is attempted. A .RENAME request to other devices is ignored. 

Files cannot be protected or unprotected using the .RENAME request. To 
change the protection status of a file, use the .FPROT request or the PRO- 
TECT and UNPROTECT commands. 

File dates can be changed using the .SFDAT request. 

Errors: 



Code 


1 
2 
3 

Example: 



Explanation 

Channel open. 

File not found. 

Invalid operation. 

A file by that name already exists and is protected. 
A RENAME was not done. 



.TITLE RENAME. MAC 



.RENAME - This is an example in the use of the .RENAME re-iuest. 
The example renames a file accordins to filespecs input thru the 
.CSISPC request. 



START! 



.MCALL 


.RENAMEi. PRINT. 


EXIT 




.MCALL 


.CSISPC. .FETCH. 


SRESET 




ERRBYT 


= 52 




iEr ro r byte location 


.CSISPC 


• FILESP.«DEFES<T 




iUse .CSISPC to set file specs 


.FETCH 


•HANLOD.«FILEBP 




iGet Handler from outspec 


BCS 


Z» 




iBranoh if failed 


Moy 


•FILESPiRZ 




iRZ => Outspeo 


Moy 


«FILESP+4B,R3 




!R3 => Inspec 


Moy 


SRZ.FILESP+SS 




iCopy device spec to inspeo 


.REPT 


a 




iCopy outspec behind inspec 


Moy 


(RZ)+.(R3)+ 




ifor .RENAME... 


.ENDR 








.RENAME 


•AREA.»0.«FILESP+3G 


{Rename input file 


BCC 


1* 




^Operation successful 


DECB 


e»ERRBYT 




!MaKe error code -1.0 or +1 


BEO 


3» 




iBranoh if File-Not-Found 


MOU 


•ILLDP.RO 




illleial operation-set up mss 


BR 


5* 




.Branch to report error 
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1$: 


.SRESET 
.EXIT 




2*! 


Moy 


ttNOHANiRO 




BR 


5« 


3$: 


Moy 


"NOFIL (RO 


5*: 


.PRINT 






BR 


1$ 


AREA! 


.BLKM 


5 


DEFEXT: 


.MORO 


lO (0 fO 


NOFIL: 


.ASCIZ 


/?File not, found?/ 


ILLOP! 


.ASCIZ 


/?Ille3al Operation?/ 


NOHAN: 


.ASCIZ 
.EVEN 


/?. FETCH Failed?/ 


FILESP: 


.BLKW 


3S.*2 


HANLOD 


= , 






.END 


START 



iDismiss handlers 

iExi t p rosl ram 

SFetch failed-set up messaile 

iBranch to report error 

iFile not found-setup wessase 

iPrint error messaae 

iThen exit yia .SRESET 

iEMT Arsfument blocK 

iNo default extensions 

lError Message text 



iCSISPC Input Area 
iHandlers can load here. 



2.72 .REOPEN 



The .REOPEN request associates the channel that was specified with a file 
on which a .SAVESTATUS was performed. The .SAVESTATUS/.REOPEN 
combination is useful when a large number of files must be operated on at 
one time. As many files as are needed can be opened with .LOOKUP, and 
their status preserved with .SAVESTATUS. When data is required from a 
file, a .REOPEN enables the program to read from the file. The .REOPEN 
need not be done on the same channel as the original .LOOKUP and 
.SAVESTATUS. 

Macro Call: .REOPEN area,chan,cblk 

where: 

area is the address of a two-word EMT argument block 

chan is a channel number in the range 0-376(octal) 

cblk is the address of the five-word block where the channel status 
information was stored 

Request Format: 

RO — > area: 



chan 



cblk 



Errors: 

Code 





Explanation 

The specified channel is in use. The .REOPEN has not been 
done. 



Example: 

Refer to the example for the .SAVESTATUS request. 

2.73 .RSUM (FB and XM Only) 

See .SPND/.RSUM (Section 2.84). 
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2.74 .SAVESTATUS 



The .SAVESTATUS request stores five words of channel status information 
into a user-specified area of memory. These words contain all the informa- 
tion RT-11 requires to completely define a file. When a .SAVESTATUS is 
done, the data words are placed in memory, the specified channel is freed, 
and the file is closed. When the saved channel data is required, the 
.REOPEN request is used. 

.SAVESTATUS can only be used if a file has been opened with .LOOKUP. 
If .ENTER was used, .SAVESTATUS is invalid and returns an error. Note 
that .SAVESTATUS is not valid for magtape or cassette files. 

The .SAVESTATUS/.REOPEN requests are used together to open many 
files on a limited number of channels or to allow all .LOOKUPS to be done 
at once to avoid USR swapping. 

While the .SAVESTATUS/.REOPEN combination is useful, care must be 
observed when using it. In particular, the following cases should be 
avoided: 

1. If a .SAVESTATUS is performed and the same file is then deleted 
before it is reopened, it becomes available as an empty space that 
could be used by the .ENTER command. If this sequence occurs, 
the contents of the file supposedly saved changes. 

2. Although the device handler for the required peripheral need not 
be in memory for execution of a .REOPEN, the handler must be 
in memory when a .READ or .WRITE is executed, or a fatal error 
is generated. 

One of the more common uses of .SAVESTATUS and .REOPEN is to con- 
solidate all directory access motion and code at one place in the program. 
All files necessary are opened and their status saved, then they are re- 
opened one at a time as needed. USR swapping can be minimized by lock- 
ing in the USR, doing .LOOKUP requests as needed, using .SAVESTATUS 
to save the file data, and then unlocking the USR. The user should be 
aware of the consequences of locking in the USR in a foreground/back- 
ground environment. If the background job locks in the USR when the 
foreground job requires it, the foreground job is delayed until the back- 
ground job unlocks the USR. 

Macro Call: .SAVESTATUS area,chan,cblk 

where: 

area is the address of a two-word EMT argument block 

chan is a channel number in the range 0-376(octal) 

cblk is the address of the five- word user memory block where the 
channel status information is to be stored 

Request Format: 



RO -^ area: 



chan 



cblk 
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The five words returned by .SAVESTATUS contain the following informa- 
tion: 

Contents 

Channel status word 

Starting block number of this file, 

or if non-file-structured 

Length of file 

Highest block written 

Number of pending requests 

Device unit number 



Explanation 

The channel specified is not currently associated with any 
files; that is, a previous .LOOKUP on the channel was never 
done. 

The file was opened with an .ENTER request, or a .SAVE- 
STATUS request was performed for a magtape or cassette 
file. 



Name 

C.CSW 
C.SBLK 


Offset 


2 


C.LENG 
C.USED 
C.DEVQ 

C.UNIT 


4 

6 

10 

11 


Errors: 




Code 


• 





The cha 



Example: 



.TITLE SAUEST.MAC 



i + 



i .SftyESTATUS / .REOPEN - This is an example in the use of the .SAyESTATUS 

! /.REOPEN requests. These requests are most cooMMonly used together to 

! consolidate access to the USR at one place in the prosfrani or if the 

! program must access more files than there are I/O channels available. 

; Onoe a channel has been opened* its status may be saued i to be re-opened 

; and used later as needed. This example merges 2-6 files into 1 filei 
i-reading all input files on one channel. 



START! 



1«: 



Z«! 

at: 

5*: 



.MCALL 


. CSIGEN. .SAMESTATl 


.MCALL 


. READW. .WRITWi.PR: 


ERRBYT 


= 52 


.CSIGEN 


wDSPACE.ftDEFEXT 


Moy 


ttS.Ra 


Moy 


»AREAiR3 


MOM 


•SAMBLKiRS 


.SAFEST 


R3.Ra.R5 


BCS 


Zt 


ADD 


«1Z.R5 


INC 


R4 


CMP 


«8. iRfl 


BGE 


1» 


Moy 


• SAWBLK .R5 


BEQ 


7* 


.REOPEN 


R3.W3.R5 


CLR 


BLK 


.READW 


R3 ,«3,«BUFFR,«Z5B 


BCC 


Gi 


TSTB 


e«ERRBYT 


BNE 


8t 


.PURGE 


«3 


ADD 


• 12 .R5 


TST 


SR5 


BNE 


at 


.CLOSE 


• 


.PRINT 


«DDNE 


.EXIT 





iError byte loc in SYSCOM 

SGet file specsiopen files. load handlers 
iRa = 1st input channel 
!R3 => EMT Argument block 
iRS => Channel sauestatus blocKs 
iSave channel status 
.Branch if channel neuer opened 
!AdJust R5 to point to next status blocK 
.Bump Ra to = next input channel 
iDone all input channels? 
.Branch if not 

<R5 => to 1st saved channel status 
.Branch if no input files 
iRe-open input channel on Ch 3 
iStart reading ulth blocK 
.BLK ;Read a block 

SBranch if no error 

iCheok if error = EOF 

.Branch if not EOF 

iClear input channel for re-use 

.Point R5 to next saued ch status 

iAny more input channels? 

.Branch if yes 

iMe're dcne.i.close output channel 

{Announce merge complete 

iExi t pros ram 
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6$: 



7t: 
8$: 

9t! 

AREA: 

BLK: 

WBLK! 

SAVBLK: 

DEFEXT: 

NQINP: 

WERR: 

RERR: 

DONE: 

BUFFR; 
DSPACE 



.WRITW 

INC 

INC 

BCC 

MOy 

BR 

Moy 

BR 

Moy 

.PRINT 

.EXIT 

.BLKN 

.UORD 

.MQRD 

.BLKN 

.NDRD 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.EUEN 

.BLKM 

.END 



R3 i«0 ("BUFFR i*25B. iWBLK iWrite block Ju5t read 



WBLK 

BLK 

5* 

»WERR iRO 

3$ 

•NOINP .RO 

9« 

• RERR.RO 



5 





30. 

)0 (0 tO 

/?No input files?/ 

/?Write Error?/ 

/?Read Error?/ 

/I-Q Transfer Completed/ 



Buwp to next output block 

same ffor input blh (doesn't 

Branch if no error on write 

Write error - RO => messase 

Me r ae . . . 

RO => No input files message 

me r!(e . . . 

RO = > Read error ms 3 

Report error 

then exit pros ram 

EMT flrS-uwent block 

Current read block 

Cur rent write block 

Saued channel status area 

No default extensions for CSIGEN 

Error friessades 



f eot C bi t ) 



25G. 



START 



i I/O buf f e r 
{Handlers start here. 



2.75 .SCCA 



The .SCCA request: 

1. Inhibits a CTRL/C abort 

2. Indicates when a double CTRL/C is initiated at the keyboard 

3. Distinguishes between single and double CTRL/C commands 

CTRL/C characters are placed in the input ring buffer and are treated as 
normal control characters without specific system functions. The request 
requires a terminal status word address that is used to report consecutive 
CTRL/C input sequences. Bit 15 of the status word is set when consecutive 
CTRL/C characters are detected. The program must clear the bit. 

There are three cautions to observe when using .SCCA. First, the request 
can cause CTRL/C to appear in the terminal input stream, and therefore 
the program must provide a way to handle it. Second, the request makes it 
impossible to terminate program loops from the console, and therefore it 
should be used only in thoroughly tested, reliable programs. When .SCCA 
is in effect and the program enters an interminable loop, the system must 
be halted and re-bootstrapped. The keyboard monitor ABORT command is 
not inhibited by .SCCA, however, so foreground and system jobs can still be 
terminated in this manner. Third, a CTRL/C from indirect command files is 
not intercepted by the .SCCA request. 

A .SCCA request with a status word address of zero disables the intercept 
and re-enables CTRL/C system action. 

Macro Call; .SCCA area,addr 

where: 

area is the address of a two-word parameter block 

addr is the address of a terminal status word (an address of re- 
enables the CTRL/C command) 
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Request Format: 
RO -^ area: 

Errors: 

None. 
Example: 



35 



addr 





.MCALL 


.SCCA. 


RCVDC.EXIT 




.MCALL 


,QSET, 


SPNOf.RSUM 


START: 


.OSET 


•OELEM 


.«! 




.SCCA 


•MAREA 


.«SCCA 


1«: 


CALL 


CWATCH 






.Rcyoc 


SMAREA 


iHMBUFF.saO. 



.TITLE SCCA. MAC 



.SCCA - This is an example in the use of the .SCCA re-iuest. The 
eKample is a simulation of a mainline Forearound proiram which is 
currently suspended waitins for a message from the BacKiroundt but which 
needs to close a file (perhaps opened by a .ENTER ?) before aborting 
from CTRL-C action. A completion routine periodically inspects the CTRL-C 
status word and resumes the mainline if double CTRL-C is entered. 
NOTE: This example MUST be run as a FG Job under an FB monitor. 



.PRINT i.MRKT 

{Allocate another 0-Element 
ilnhibit *C*C action by monitor 
iStart "watchdo£f" completion rtne 
*MESG iLooK for a message 

!No errors - there's always BG 
• Other processinsl here... 

iAnnounce we're soins to suspend 
iSuspend to wait for message 
iWe'we been .RSUMed . . , "C'C hit?? 
iB ranch if yes 
lOtherwisB assume messasfe came in.< 



; L p . . . 

iCheoK if 'C'C ente red . . . 
iBranch if no 

i Yes... wake up the mainline 
ithen leaue compieticn code 
tl iSchedule to run aslain in 1( 
ithen leaue completion code 

iAnnounce we're abortinsr 
iprooeed with "orderly" abort 



iExi t the p ro^ram 

iExt ra 0-El ement 

iMessasle buffer 

iEMT Argument blocKs 

i 

iTime out in 10 seconds 

i ~C'C Status word 





.PRINT 


•SLEEP 




.SPND 






TST 


SCCA 




BNE 

■ 


CLOSE 




1 

i <p rocess 


messaste he re > 




BR 


1* 


CWATCH! 


TST 


SCCA 




BEQ 


MARK 


MESG: 


.RSUM 
RETURN 




MARK! 


.MRKT 
RETURN 


«CAREA.«TIME.»CWATCh 


CLOSE! 


.PRINT 


•ABORT 




i < u t p u t 

■ 


files(s) closed here> 




.EXIT 




OELEM: 


.5LKM 


7 


MBUFF: 


.BLKU 


41 . 


MAREA! 


.BLKW 


5 


CAREA! 


.BLKW 


a 


TIME! 


.MORD 


.BOO.. 


SCCA: 


.WORD 





ABORT: 


.ASCIZ 


/?! Abort AcKnowled: 


SLEEP: 


.ASCIZ 


/ ! Mainl ine Suspend: 



.END 



START 



2.76 .SDAT/.SDATC/.SDATW (FB and XM Only) 

The .SDAT/.SDATC/.SDATW requests are used with the .RCVD/ 
.RCVDW/.RCVDC calls to allow message transfers between a foreground 
job and a background job under the FB or XM monitors. .SDAT transfers 
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are similar to .WRITE requests, where data transfer is not to a peripheral 
but from one job to another. Additional I/O queue elements should be allo- 
cated for buffered I/O operations in .SDAT and .SDATC requests (see 
.QSET). 

Message handling in the FB monitor does not check for a word count of zero 
before queuing a send or receive data request. Since RT-11 distinguishes a 
send from a receive by complementing the word count, a .SDATW of zero 
words is treated as a .RCVDW of zero words. Thus, avoid a word count of 
zero at all times when using a .SDATW request. 

Be particularly careful if you use both synchronous (.RCVDW and 
.SDATW) and asynchronous (.RCVDC and .SDATC) requests in the same 
program. If you issue a mainline .SDATW while there is a pending 
.RCVDC, the .SDATW will wait until the .RCVDC is satisfied. If the com- 
pletion routine for the .RCVDC issues another .RCVDC, the mainline 
.SDATW will never complete. In general, you should avoid the use of both 
synchronous and asynchronous message requests in the same program. 



.SDAT 
Macro Call: 

where: 



.SDAT area,buf,wcnt 



area is the address of a five-word EMT argument block 

buf is the buffer address of the beginning of the message to be 
transferred 

went is the number of words to transfer 

Request Format: 

RO 



area: 



25 







unused 



buf 



went 



Errors: 



Code 





Explanation 

No other job exists. (A job exists as long as it is loaded, 
whether or not it is active.) 



Example: 



i + 

i .SOAT/.RCVD - This is an example in the use of the .SDAT/.RCVD 

I requests. The example is actually two prodramsi a Background Job 

i which sends messaSes i and a Foreslround Job > which receives them. 

iNOTE; Each proilram should be assembled and linKed separatelvi 

i- 



. TITLE SDATF.MftC 
Foreground Pro^raMi.< 
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.MCALL 



•RCVD (.MWAIT..PRINT..EXIT 



STARTF! 



.RCMD 
! 



• AREA .«MBUFF.«aO. 



iReiuest a messaie up to 80 char. 
iNo error possible - always a BG 





.PRINT 

i 


•FGJOB 




1 

.MWAIT 


' 




TST 


MBUFF+2 




BEO 


FEXIT 




.PRINT 


SFMSG 




.PRINT 


«MBUFF+2 




BR 


STARTF 


FEXIT: 


.EXIT 




AREA: 


.BLKU 


5 


MBUFF: 


.BLKU 


41, 




.MORD 





FGJDB: 


.ASCIZ 


/Hi - FG a 


FMSG: 


.ASCIZ 


/Hey BG - 




.END 


MWAITF 




.TITLE 


STARTS. MAC 



iDo some other proces&insf 
niKe announciind FG active. 



iUait for messaae to arrive.. 

iNul 1 message? 

iYes...exit the prosram 

lAnnounce uie slot the message. 

iand echo it bacK 

iLoop to Set another one 

iExit program 



lEMT Arduinent 

iBuffer - Mss 

iMake sure 80 

aliue and well and waitins 

Got your fnessasre it reads 



Block 
length 



1 



char messaae ends ASCIZ 
for a Message!/ 



i + 

I Background Prodram - Send a 'null' message to stop both programs 





.MCALL 


.SDAT .. MWAIT. .GT 


STARTS: 


CLR 


BUFF 




.GTLIN 


•BUFF .SPROMT 




.SDAT 


•AREA.»BUFF.»aO. 




BCB 


1« 




.MWAIT 






TST 


BUFF 




BNE 


STARTB 




.EXIT 




1$: 


.PRINT 
.EXIT 


• NOFG 


AREA: 


.BLKW 


5 


BUFF; 


.BLKU 


40. 


PROMT: 


.ASCII 


/Enter messaae t 


NDFG: 


.ASCIZ 


/?No FG?/ 




.END 


MWAITB 


.SDATC 






Macro Call: .SDATC area,buf,wc 



to be 



iClear 1st word 

iGet something to send to FG from TTY 
iSend input as message to FG 
iBranch on error - No FG 
iWait for messasle to be sent 
iSent a null messasfe? 
iNoi.iloop to send another message. 
iVes ... exit p rosram 
;No FG ! 
fExit prosrram 
iEMT Argument Block 
iUp to 80 char message 
sent to FG Job/< 15X 12>/ >/<200> 



where: 



area 
buf 

went 
crtn 



is the address of a five-word EMT argument block 

is the buffer address of the beginning of the message to be 
transferred 

is the number of words to transfer 

is the address of the completion routine to be entered when 
the message has been transmitted 



Request Format: 
RO -^ area: 



25 







unused 



buf 



went 



crtn 
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Errors: 

Code 




Explanation 

No other job exists. (A job exists as long as it is loaded, 
whether or not it is active.) 



Example: 

See the example following .SDATW. 

.SDATW 

Macro Call: .SDATW area,buf,wcnt 

where: 



area is the address of a five-word EMT argument block 

buf is the buffer address of the beginning of the message to be 
transferred 

went is the number of words to transfer 

Request Format: 



RO 



area: 



25 







unused 



buf 



went 







Errors: 

Code 



Example: 



Explanation 

No other job exists. (A job exists as long as it is loaded, 
whether or not it is active.) 



.SDflTW/RCyDW - This is an example in the use of the , SDATW/ . RCgOW 
reiuestsi The example consists of two prosrams! a Foreground Job 
uhich creates a file and sends a messase to a BacKsround prosram 
which copies the FG channel and reads a record from the file. Both 
prosrams must be assembled and linKed separately. 

.TITLE SDflTWF.MAC 
i + 

I This is the Foresround program ... 
! - 

.MCfiLL .ENTER .. PRINT . . BDATW . . EXIT . . RCyDW . . CLOSE . . WRITW 



iR5 => EMT araument blocK 
■Create a 5 blocK file 
i»a iWrite a record BG is interested in 
iBranch on error 
iSend message with info to BG 
!Do some other processins 
iNhen it's time to exit. maKe sure 
iBG is done with the file 
iTell user we're exiting 
SExit the pros ram 



TFs 


MOM 


"AREA .R5 




.ENTER 


R5.O0 .*FILE.»5 




.WRITW 


R5.»0 i»RECRD .«25G 




BCS 


ENTERR 




.SDATW 


R5 >«BUFR.»2 




.RCVDW 


R5.«BUFR,«1 




.CLOSE 


• 




.PRINT 


•FEXIT 




.EXIT 
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ENTERR: 


♦PRINT 
♦ EXIT 


■ERMSG 




iPrint error messasre 
ithen exit 


FILE: 


.RAD50 


/DK OUFILE/ 


iFUe spec for .ENTER 




.RAD50 


/TMP/ 






AREA: 


.BLKW 


5 




iEMT arsument block 


BUFR: 


.MORD 







iChannel » 




.NORD 


a 




iBlook • 


RECRD: 


.BLKW 


256. 




!Fi 1 e record 


ERMSG: 


.ASCIZ 


/?Ente r 


Erro r?/ 


iError wessaSe text 


FEXIT: 


.ASCIZ 
.END 


/FG Job 
STARTF 


exitins/ 


iExit Message 



; + 



.TITLE SDATWB.MAC 

i This is the BacKsround program ... 
I - 

.MCALL .CHCOPY . .RCVDW » ♦READW . . EXIT .. PRINT .. SDATW 



STARTB: 



1$: 



3$! 

at: 

AREA: 

MSG: 

BUFF: 

BEXIT: 

NO JOB : 

NOCH: 

RDERR: 



Moy 

.RCMDW 

BCS 

.CHCOPY 

BCS 

.READI4 

BCS 

! 

, SDATW 

♦PRINT 

.EXIT 

MOy 

BR 

Moy 

BR 

Moy 

.PRINT 

.EXIT 

.BLKW 

.BLKW 

.BLKW 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.END 



«AREA.R5 

R5.»MSG.«2 

1* 

R5.«0.MSG + 2 

2» 

R5 i«0.»8UFF .«25B. .MSG^ 

3* 

R5 .»MSG.«1 
sBEXIT 

»NDJOB (RO 

at 

»NOCH iRO 

at 
srderr.ro 



5 

3 

258. 

/Channel-Record copy 

/?No FG Job?/ 

/?FG channel not open 

/?Read Error?/ 

STARTB 



iR5 => EMT ars blocK 

(Wait for message from FG 

iBranoh if no FG 

iChannel « is 1st word of message 

iBranoh if FG channel not open 

a iRead blooK which is 2nd word of msa 

iBranoh if read error 

iContinue processing... 

iTell FG we're thru with file 

iTell user we're thru 

ithen exit prcd ram 

iRO => No FG error mss 

iBranoh to print msS 

iRO => FG oh not open mss 

iB ranch . . . 

iRO = > Read err ws i 

iPrint proper error mss 

ithen exit. 

iEMT ardument blK 

iMessa9e buffer 

iFi le buf f e r 
successful/ 

iError Messages... 
?/ 



2.77 .SDTTM 



The .SDTTM (Set date and time) request allows your program to set the 
system date and time. 



Macro Call: 

where: 

area 
addr 



.SDTTM area.addr 



is the address of a two-word EMT argument block 

is the address of a three-word block in user memory that con- 
tains the new date and time 



Request Format: 
RO — » area: 



40 



addr 



The first word of the three-word parameter block contains the new system 
date in internal format (see the .DATE programmed request). If this word 
is -1 (represents an illegal date), the monitor ignores it. Put a -1 in the 
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first word of the parameter block if you want to change only the system 
time. If the first parameter word is positive, it becomes the new system 
date. Note that the monitor does no further checking on the date word. To 
be sure of a valid system date, you must specify a value between 1 and 
12(decimal) in the month field (bits 13-10) and a value between 1 and the 
month length in the day field (bits 9-5). Bits 14 and 15 must be zero. 

The second and third words of the parameter block are the new high-order 
and low-order time values, respectively. This value is the double-precision 
number of ticks since midnight. If the high-order time word is negative, the 
monitor ignores the new time. Put a negative value in the second word of 
the parameter block if you want to change only the system date. If the 
second parameter word is positive, the new time becomes the system time. 
The monitor does no further checking on the new time. To be sure of a valid 
system time, you must specify a legal number of ticks for the system line 
frequency. For a 60 Hz clock, the high-order time may not be larger than 
117(octal), and if it is equal to 117, the low-order time may not be equal to 
or larger than 15000(octal). For a 50 Hz clock, the high-order time may not 
be larger than lOl(octal), and if it is equal to 101, the low-order time may 
not be equal to or larger than 165400(octal). 

Changing the date and/or time has no effect on any outstanding mark time 
or timed wait requests. 

Errors: 

None. 

Example: 



.TITLE SDTTH.MAC 



.SDTTM.MAC - This is an example in the use of the .SDTTM request. 
The example is a Day 1 i Sht/Standa rd Time utility - to switch the 
current system time from Standard to Daylislht or uice uersai call 
the program as a subroutine at the proper entry point. 





.MCALL 


.SDTTM 


..PRINT. 


.EXIT. .GTIM 




.GLOBL 


STD>DALITE 




STD: 


COM 


HR 




.Switch to STD time... 




NEG 


HR + 2 




iMaKe one hr in clocK ticKs 


DflLITE: 


.GTIM 


•AREAi 


• TIME 


(Get the current time 




CALL 


JADD 




.Adjust +/- 1 hour 




.SDTTM 


oAREAi 


•NEWDT 


iSet the new system time 




.GTIM 


•AREA) 


• TIME 


.Force date rollouer (if any) 




RETURN 






.Return to caller 


NEWDT: 


.WORD 


-1 




i. SDTTM arsuments - No new date 


TIME! 


.UORD 


0.0 




.New time 


HR: 


.MORD 
.UORD 


3 
35700 




iOne hour in clocK ticKs <60 cycle 
; ClocK! ) 


AREA: 


.WORD 


0.0 




iEMT Argument BlocK 


JADD: 








iDouble precision inteser add 




Moy 


• HR.Rfl 




iR4 -> Lou order of System time + 




Moy 


•AREA. 


R3 


iR3 => Low order of One hour + 2 




Moy 


• HR.Rl 




iRl => Low order of new time 




Moy 


-(RH) , 


R2 


.Put low order of 1st operand in R 



+ 2 
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ADD 


-(R3) .R2 


MDV 


-(R4) ,R5 


ADC 


R5 


ADD 


-(R3) ,R5 


Moy 


R2 .-(Rl) 


Mog 


R5 i-(Rl) 


RETURN 




.END 





!Add in low order of operand «2 
iPut hisrh order of operand «1 in R5 
iAdd in carry (no overflow possible 
iAdd in hish order of operand «2 
i ( ditto ! ) 
•Store result where wanted 

iReturn to caller 



! ) 



2.78 .SERR 

See .HERR/.SERR (Section 2.38). 

2.79 .SETTOP 

The .SETTOP request specifies a new address as a program's upper limit. 
The monitor determines whether this address is legal and whether or not a 
memory swap is necessary when the USR is required. For instance, if the 
program specified an upper limit below the start address of USR (normally 
specified in offset 266 in the resident monitor), no swapping is necessary, as 
the program does not overlay the USR. If .SETTOP from the background 
specifies a high limit greater than the address of the USR and a SET USR 
NOSWAP command has not been given, a memory swap is required. The 
use of .SETTOP in an extended memory environment is described at the 
end of this section. 

Careful use of the .SETTOP request provides a significant improvement in 
the performance of your program. An approach that is used by several of 
the system-supplied programs is as follows: 

1. A .SETTOP is done to the high limit of the code in a program 
before buffers or work areas are allocated. If the program is 
aborted, minimal writing of the user program to the swap blocks 
(SWAP.SYS) occurs. However, the program is allowed to be re- 
started successfully. 

2. A user command line is now read through .CSISPC or .GTLIN. 
An appropriate USR swap address is set in location 46. Successive 
.DSTATUS, .SETTOP, and .FETCH requests are performed to 
load necessary device handlers. This attempts to keep the USR 
resident as long as possible during the procedure. 

3. Buffers and work areas are allocated as needed with appropriate 
.SETTOP requests being issued to account for their size. Fre- 
quently, a .SETTOP of #-2 is performed to request all available 
memory to be given to the program. This can be more useful than 
keeping the USR resident. 

4. If the process has a well-defined closing phase, another .SETTOP 
can be issued to cause the USR to become resident again to close 
files (the user should remember to set location 46 to zero if this is 
done, so that the USR again swaps in the normal area). On return 
from .SETTOP, both RO and the word in location 50(octal) contain 
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the highest memory address allocated for use. If the job requested 
an address higher than the highest address legal for the request- 
ing job, the address returned is the highest legal address for the 
job rather than the requested address. 

When doing a final exit from a program, the monitor writes the 
program to the file SWAP.SYS and then reads in the KMON. A 
.SETTOP #0 at exit time prevents the monitor from swapping out 
the program to the swap blocks (SWAP.SYS) before reading in 
the KMON, thus saving time. This procedure is especially useful 
on a diskette system when indirect command files are used to run 
a sequence of programs. The monitor command SET EXIT 
NOSWAP also disables program swapping. 

Macro Call: .SETTOP addr 

where: 



addr is the address of the highest word of the area desired (the last 
word the program will modify, not the first word it leaves 
untouched) 



Notes: 



1. 



A program should never do a .SETTOP and assume that its new upper 
limit is the address it requested. It must always examine the returned 
contents of RO or location 50 to determine its actual high address. 

It is imperative that the value returned in RO or location 50 be used as 
the absolute upper limit. If this value is exceeded, vital parts of the 
monitor can be destroyed. 



Errors: 



None. 



Example: 



.TITLE SETTOP. MAC 



.SETTOP - This is an example in the use of the .SETTOP reiuest. The 
example tries to obtain as much metnory as possible usina the .SETTOP 
re-iuest) which will force the USR into a swappins mode. The .LOCK request 
will brins the USR into memory (over the hisrh 2K of our little prosram M 
and force it to remain there until an .UNLOCK is issued. 



START: 



Z$: 



.MCALL 
.MCALL 




.LOCK ..UNLOCK .. 
.SETTOP, .PRINT, 


LOOKUP 
.EXIT 


SYSPTR= 


54 










.SETTOP 


@»SYSPTR 








.LOCK 

.LOOKUP 

BCC 

.PRINT 

.EXIT 




• AREA 

1« 

»LMSG 


•to 


,»FILE1 





iPointer to besinninS of RMON 



!Try to allocate all of 

!RMON) 

ibrina USR into memory 

iLOOKUP a file on channel 

iBranch if successful 

iPrint Error Messase 

ithen exit prosram 



memory (up to 
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1$: .PRINT «F1FND lAnncunce our success 

MOM «AREA)RO iRO => EMT ftrauwent SlooK 

INC SRO ilnorement low byte of 1st arS (ohan •) 

MOU •FILE2t2(R0) iFill in pointer to new filespec 

.LOOKUP iDo the .LOOKUP froM filled in arS blooK 

ipointed to by RO. 

BCS 2$ iBranch on error 

.PRINT sFZFND iSay we found it 

.UNLOCK inow release the USR 

.EXIT iand exit proSraw 

AREA; .BLKW 3 iEMT Arsument BlocK 

FILEl: .RAD50 /DK/ iA File we're sure to find 

.RAD50 /PIP / 

.RAD50 /SAW/ 

FILE2I .RAD50 /DK/ iAnother file we misht find 

,RAD50 /TECO / 

.RAD50 /SAW/ 

LMSG: .ASCIZ /?Error on .LOOKUP?/ iError messaSe 

FIFND: .ASCIZ /...Found PIP.SAV/ 

F2FND; .ASCIZ /...Found TECD.SAy/ 

.EVEN 

.END START 

2.79.1 .SETTOP in an Extended Memory Environment 

You can enable the extended memory feature of the .SETTOP programmed 
request with the linker A^ option or the LINK command with the /XM 
option (see Chapter 11 in the RT-11 System Utilities Manual or Chapter 4 
of the RT-11 System User's Guide). The RT-11 Software Support Manual 
describes in detail the .SETTOP request in an extended memory environ- 
ment. The .SETTOP request operates in privileged and virtual jobs as fol- 
lows: 

Privileged Jobs 

1. A .SETTOP that requests an upper limit below the virtual high 
limit of the program will always return the virtual high limit of 
the program. The virtual high limit is the last address in the 
highest PAR that the program uses. In this case, a value can 
never be returned below the job's virtual high limit. 

2. A .SETTOP that requests a job's upper limit above the program's 
virtual high limit will return the highest available address as 
follows: 

a. Either the address requested or SYSLOW-2 (last used ad- 
dress, SYSLOW is next address available) is returned, which- 
ever is lower. SYSLOW is defined as the start of the USR in 
the XM monitor. 

b. If the program's virtual high limit is greater than SYSLOW 
(the user program maps over the monitor or USR), the virtual 
high limit of the program will always be returned. 

Virtual Jobs 

1. As in privileged jobs, a .SETTOP request can never get less than 
the virtual high limit of the job. 
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2. If a .SETTOP requests an upper limit greater than the virtual 
high limit, the following occurs: 

a. If the virtual high limit equals 177776, this value is returned 
since this is the address limit in virtual memory. Otherwise, 
a new region and window will be created. The size of the 
region and window will be determined by the argument speci- 
fied to the .SETTOP or by the amount of extended memory 
that is available, whichever value is smaller. The .SETTOP 
argument rounded to a 32-word boundary minus the high 
.LIMIT value for the program equals the size of the region 
and window (see the LINK chapter of the RT-11 System Util- 
ities Manual and the RT-11 Software Support Manual for a 
description of the .LIMIT directive in extended memory). If 
there are no region control blocks, window control blocks, or 
extended memory available, the program's virtual high limit 
is returned. The .SETTOP request uses one of the region and 
window control blocks allocated to the user, thus one less 
block is available to the program if the linker /V option is 
used. 

b. Additional .SETTOP requests can only remap the original 
window created by the first .SETTOP. Thus, additional re- 
quests will return an address no higher than that established 
by the first request and no lower than the program virtual 
high limit. An additional .SETTOP request whose argument 
is higher than the first request will cause the entire first 
window to be mapped. An additional .SETTOP request whose 
argument specifies a value below the virtual high limit elimi- 
nates the region and window. If another .SETTOP request 
then follows, it may create a new region and window. 



2.80 .SFDAT 



The .SFDAT programmed request allows a program to set or modify the 
creation date in a file's directory entry. Dates on protected as well as unpro- 
tected files can be changed. 

Macro Call: .SFDAT area, chan, dblk, date 

where: 

area is the address of a three-word EMT argument block 

chan is a channel number in the range 0-376 

dblk is the address of a four-word block containing a filespec in 
Radix-50 

date is the address of the new date, in RT-11 format If this argu- 
ment is #0, the system date is used; bits 14 and 15 are always 
set to 0, but no other check is made for an illegal date 
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Request Format: 
RO -^ area: 



42 chan 



dblk 



date 



Errors: 

Code 



1 

2 

Example: 

Refer to the example for the .FPROT request 



Explanation 

Channel in use 

File not found 

Invalid operation (device not file structured) 



2.81 SFPA (Special Feature) 



The .SFPA request allows users with floating-point hardware to set trap 
addresses to be entered when a floating-point exception occurs. If no user 
trap address is specified and a floating-point (FP) exception occurs, a 
?MON-F-FPU trap occurs, and the job is aborted. 

.SFPA area,addr 

is the address of a two- word EMT argument block 

is the address of the routine to be entered when an exception 
occurs 

Request Format: 
RO — > area: 



Macro Call: 

where: 

area 
addr 



30 







addr 



Notes: 

1. The user trap routine must save and restore any registers it uses. It 
exits with an RTI instruction. 

2. If the address argument is #0, user floating-point routines are disabled 
and the fatal ?MON—F—FPU trap error is produced by any further 
traps. 

3. In the FB environment, an address value of #1 indicates that the FP 
registers should be switched when a context switch occurs, but no user 
traps are enabled. This allows both jobs to use the FP unit. An address 
of #1 to the SJ monitor is equivalent to an address of #0. 

4. When the user routine is activated, it is necessary to re-execute an 
.SFPA request, as the monitor disables user traps as soon as one is 
serviced. It does this to prevent a possible infinite loop from being set 
up by repeated floating-point exceptions. 
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5. If the FPU is being used, the instruction STST -(SP) is executed by the 
monitor before entering the user's trap routine. Thus, the trap routine 
must pop the two status words off the stack before doing an RTI. The 
program can tell if FP hardware is available by examining the configu- 
ration word in the monitor. 

Errors: 

None. 

Example: 

.TITLE SFPft.MAC 



.SFPA - This is an eKample in the use of the .SFPft request. This 
example is a skeleton prosiram which demonstrates how to set up a 
Floating Point trap routine) and the minimum action that routine 
must taKe before dismissing the error trap. 



START: 



• MCflLL .SFPA. .EXIT 

SYSPTR = 5a 
CONFIG = 300 
FPU = 100 



SFPA 



.EXIT 



»AREA.»FPTRAP 



iLoc of besinnins of Monitor 
lOffset to Monitor configuration wd 
iFPU present bit 
iMainline prodram... 



iSet UP FPU error trap 
{continue mainline program 
(Exit pro dram 



FPTRAPi 


i 

i 


• 


iFPU exception routine 
iHandle exception... 


CKFPU: 


Moy 


@»SYSPTR,RO 


!R0 => base of RMON 




BIT 


»FP11 .CDNFIG(RO) 


iCheoK for FPU hdwe 




BEO 


1$ 


iBranch if none 




CMP 


(SP)+.<SP)+ 


iMust POP status resfs off staoK! 


1«: 


RTI 




iBefore returnins from interrupt 




.END 


START 





2.82 .SPCPS (FB and XM SYSGEN Option) 

The .SPCPS (save/set mainline PC and PS) request allows a program's 
completion routine to change the flow of control of the mainline code. 
.SPCPS saves the mainline code PC and PS, and changes the mainline PC 
to a new value. If the mainline code is performing a monitor request, the 
monitor allows that request to finish before doing any rerouting. The actual 
rerouting is deferred until the mainline code is about to run. Therefore, the 
.SPCPS request returns an error if it is reissued before an earlier request 
has been honored. Furthermore, the data saved in the user block is not 
valid until the new mainline code is running. 

The .SPCPS request is a system generation feature and is available only in 
FB and XM. If a program issues this call under SJ or under a monitor not 
generated for the call, no action is taken and no error is returned. 
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Macro Call: 

where: 

area 
addr 



.SPCPS area.addr 



is the address of a two-word EMT argument block 

is the address of a three-word block in user memory that con- 
tains the new mainline PG, and that is to contain the old 
mainline PC and PS 



Request Format: 
RO — > area: 

Errors: 



41 



addr 



Code Explanation 

The program issued the .SPCPS call from the mainline code 
rather than a completion routine. 

1 A previous .SPCPS request is outstanding. 

When the program issues the .SPCPS request, the monitor saves the old 
mainline PS in the third word of the three-word block and the old mainline 
PC in the second word of the block. The monitor then changes the mainline 
PC to the contents of the first word of the block. 

Example: 





•TITLE 


SPCPS. MAC 












i + 

i .SPCPS - 


.ENABL 


LC 












This is 


an example 


in the 


use 


of 


the 


, SPCPS request. In this 


; example 


, SPCPS is used to reroute 


the 


Mainline code after an I/O 


; error op EOF is 
■ 


detected by 


a coMP 


letion 


routine . 


> - 


.MCALL 


. READC. .WRITC. CLOSE 


.PRINT 


.. CSIGEN.. EX IT ..WAIT ..SRESET 




.MCALL 


.SPCPS 














ERRBYT 


= 52 










.Error Byte location in SYSCOM 




.ENABL 


LSB 












START! 


.CSIGEN 


•DSPACE.^DEFEXT 








iUse CSIGEN to Set handlers, files 




CALL 


lOXFER 










iStart I/O 




.PRINT 


•MESSG 










iNou simulate other mainline process 


l»s 


DEC 
BR 


R5 
1* 










i (Kill some tiwe) 


FINI: 


.CLOSE 

MOV 

BR 


• 

• DONE.RO 
GBYE 










!EOF > = End of File 
iRO -H« We're done messase 
iMerse to exit proaram 


MERRi 


MOV 
BR 


• WRERR.RO 
GBYE 










iSet UP error messaSes here... 


RERR: 


Moy 


• RDERR.RO 












GBYE! 


.PRINT 

.SRESET 

.EXIT 












iPrint messasfe 

iOismiss fetched handlers 

.Exit p ro ^ ram 


HRDONE: 


.WAIT 
BCS 


• 
3* 










iWrite compl rtne.. .write successful? 
.Branch if not . . . 


lOXFER! 


.READC 
BCC 
TSTB 
BEO 


•AREA. •3.. 

5* 

e»ERRBYT 


.«B$ 








.Queue up a read 
.Branch if cK... 
.Error - is it EOF? 
.Branch if yes 
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2«i 


Moy 


•RERR. SBLOK 




iMove Read err rtne addr to arS blooK 




BR 


Hi 




!MerSe. .. 


3t: 


MOV 


•WERRiSBLOK 




iMoue Write err rtne addr to arS blooK 


at! 


TSTB 


SPCALL 




iAlreadv done a .SPCPS? 




BNE 


5* 




iYesi. .don't do another 




.SPCPS 


•AREA, "SBLOK 




iOe-rail mainline code 




INCB 


SPCALL 




iFlaS we've done this 




BCS 


7* 




iOoops! Somethins's amiss! 


5»; 


RETURN 






iLeaue completion code 


6$: 


.MAIT 


• 3 




iCoMPl et ion routine *Z - was read ok? 




BCS 


2$ 




iBranch if not 




.WRITC 


»AREA,»On.«WRDONE 


iOueue up a write .. . 




BCS 


3« 




iB ranch if error 




INC 


BLOK 




iBump block « for next read 




RETURN 






iLeaue Completion code... 


7*! 


.PRINT 
RETURN 


•SPERR 




iPrint .SPCPS failed message 


AREA: : 


.MORD 







iEMT Area block 


BLDK: 


.klORD 







iBlock «. 




.WORD 


BUFF 




iBuffer addr B. word count 




.UORD 


256. 




■already fixed in block... 




.WORD 







iCompletion routine addr 


SBLOK: 


.WORD 


FINI lOiO 




i. SPCPS ArJument block (FINI default) 


BUFF! 


.BLKW 


25G. 




iI/0 buffer 


DEFEXT: 


.WORD 


,0 tO lO 




iNo default extensions for CSIGEN 


SPCALL: 


.BYTE 
.NLIST 



BEX 




i. SPCPS called flas in case I/O error 
iCoompl rtne sets sohed. reSardless!) 


DONE: 


.ASCIZ 


/ I-O T ransf e r 


CdmpI et e/ 


!Messa9es . . . 


MESSG: 


.ASCIZ 


/< Simulatins 


Mainline 


Processing >/ 


WRERR: 


.ASCIZ 


/?Write Error?/ 




RDERR: 


.ASCIZ 


/?.Read Error?/ 




SPERR! 


.ASCIZ 


/?. SPCPS Error?/ 






.EVEN 








DSPACE 


= , 






iHandlers may be loaded starting here 



.END 



START 



2.83 .SPFUN 



This request is used with certain device handlers to do device dependent 
functions, such as rewind and backspace. It can be used with diskettes and 
some disks to allow reading and writing of absolute sectors. This request 
can determine the size of a volume mounted in a particular device unit for 
RX02 diskettes, RK06/RK07 disks, RL01/RL02 disks, MSCP disks, and log- 
ical disks. 

Macro Call: .SPFUN area,chan,func,buf,wcnt,blk[,crtn] 

where: 

area is the address of a six-word EMT argument block 

chan is a channel number in the range to 376(octal) 

func is the numerical code of the function to be performed; these 
codes must be negative (Vp^^cvj'^-;^") \t Wv^f^ %c[ 

buf is the buffer address; this parameter must be set to zero if no 
buffer is required 

went is defined in terms of the device handler associated with the 
specified channel and in terms of the specified special func- 
tion code 
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blk is also defined in terms of the device handler associated with 
the specified channel and in terms of the specified special 
function code 

crtn is the entry point of a completion routine. If left blank, is 
automatically inserted. This value is the same as for .READ, 
.READC, and .READW. 

= wait I/O (.READW) 

1 = real time (.READ) 

Value >500 = completion routine 
Request Format: 
RO -> area: 



32 chan 



blk 



buf 



went 
func I 377 



crtn 



The chan, blk, and went arguments are the same as those defined for 
.READ/.WRITE requests. They are only required when doing a .WRITE 
with extended record gap to magnetic tape. If the crtn argument is left 
blank, the requested operation completes before control returns to the user 
program. Specifying crtn as #1 is similar to executing a .READ or .WRITE 
in that the function is initiated and returns immediately to the user pro- 
gram. Use a .WAIT on the channel to make sure that the operation is 
completed. The crtn argument is a completion routine address to be entered 
when the operation is complete. 

The available functions and function codes for magtape and cassette are as 
follows: 



Function 


MM, MS, MT 


CT 


Forward to last file 




377 


Forward to last block 




376 


Forward to next file 




375 


Forward to next block 




374 


Rewind to load point 


373 


373 


Write file gap 




372 


Write EOF 


377 




Forward one block 


376 




Backspace one block 


375 




Write with extended 






file gap 


374 




Off-line rewind 


372 




Write 


371 




Read 


370 




Stream at 100 ips 






(MS only) 


367 
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The available functions and function codes for diskettes, RK06/RK07 disks, 
RLOl and RL02 disks, the logical disk handler, and MSCP disks are as 
follows: 



Function 


DX 


DM 


DY 


DL 


LD 


DU 


Read 


377 


377 


377 


377 






Write 


376 


376 


376 


376 






Write with deleted 














data mark 


375 




375 








Force a read by the 














handler of the bad 














block replacement 














table from block 1 














of the disk 




374 




374 






Return device size 


373 


373 


373 


373 


373 


373 


Read/write translation 














table 










372 


372 


Direct MSCP access 












371 



To use the .SPFUN request, the handler must be in memory and a channel 
must be associated with a file via a .LOOKUP request. 

A .SPFUN request to write absolute blocks on a diskette should not write 
anything in track if you want to use DUP or the COPY/DEVICE com- 
mand to back up the volume. DUP does not copy data in track 0. Also, you 
should be careful to specify a valid buffer address and word count. The 
monitor checks that the buf argument is in the job area, but it does not 
check buf + went. If you use the .SPFUN request, and the device handler 
for that device does not support special functions or the particular .SPFUN 
code used, the call simply returns to the program without reporting an 
error. 

For the RK06/07 handler (DM), special function codes 377 and 376 require 
the buffer size to be one word larger than necessary for the data. The first 
word of the buffer contains the error information returned as a result of the 
.SPFUN request. The data transferred as a result of the read or write 
request is found in the second and following words of the buffer. The error 
codes and information are as follows: 

Code Meaning 

100000 The I/O operation is successful. 
100200 A bad block was detected (BSE error). 

100001 An ECC error is corrected. 

100002 An error recovered on retry. 

100004 An error recovered through an offset retry. 

100010 An error recovered after recalibration. 

1774xx An error did not recover. 
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Other device-specific information is included in the RT-11 Software Sup- 
port Manual. 



Errors: 



Code 



Explanation 



Attempt to read or write past end-of-file, or invalid function 
value. 

1 Hard error occurred on channel. 

2 Channel is not open. 

Additional qualifying information for these errors is returned in the 
first two words of the blk argument status block. This information is 
given in Chapter 10 of the RT-11 Software Support Manual. 



Example: 



.TITLE SPFUN.MAC 

i + 

i .SPFUN - This is an example in the use of the iSPFUN request. The 
i example rewinds a cassette and urites out a 25G-uord buffer and 
; then a file 3ap. 



START; 



1$: 
Z»; 
3»: 

at: 

5»! 

AREA! 

BLK: 

CT: 

BUFF! 

DONE: 

FERR: 

LKERRi 

SPERR: 

WERR: 



.MCALL 
.MCALL 

.FETCH 
BCS 

.LOOKUP 
BCS 

.SPFUN 

BCS 

.NRITU 

BCS 

.SPFUN 

.PRINT 

.WAIT 

.CLOSE 

.EXIT 

MOy 
BR 
MOU 
BR 

Moy 

BR 

Moy 

.PRINT 
.EXIT 

.MDRD 

.NORD 

.RAD50 

.NORD 

.BLKM 

.ASCIZ 

.ASCIZ 

, ASCIZ 

.ASCIZ 

.ASCIZ 

.EUEN 

HSPC = 

.END 



.FETCHi .LOOKUP..SPFUN..WRITW 
.EXIT ..PR I NT.. WAIT. .CLOSE 



«HSPC.«CT 
1» 

«AREA.»ai»CT 
Z« 

»AREA i»a .#373 .«0 

3» 

»AREA.«a .»BUFF 1*256. 

4» 

• AREA i«4 i»372 .»0 i .»! 
ttOONE 

«4 

*a 

• FERR .RO 
5t 

•LKERR.RO 
5» 

• SPERR .RO 
5» 

• WERR.RO 



iFetch the CT Handler 
iBranch if failed 
iOpen channel 4 for output 
iBranch if error (should newer hap- 
1 pen ! ) 

iReulnd to BOT usins Synchronous I/O 
!Branch on error 
.BLK iWrite one block 
iBranch on error 

iWrite a file flap uith As/nch I/O 
iAnnounce that we're done 
iWait for file ^ap operation to finish 
iClose the file 
ithen exit the prosram 

iProcess errors here... 



iPrint error message 
ithen exit program 



iEMT ArSument block 



0.0.0.0.0 

/CT / 

0.0.0 

25G. 

/All done 1/ 

/?. FETCH Error?/ 

/?, LOOKUP Error?/ 

/?Speoial Function Error?/ 

/?Write Error?/ 



iCassette Device Descriptor 
iNul 1 f i 1 Bspec 
iOutPut buffer 
iMessasle text... 



iHandler can load in here.. 



START 
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1 





2 






2.84 .SPND/.RSUM (FB and XM Only) 

The .SPND/.RSUM requests control execution of a job's mainline code (the 
code that is not executing as a result of a completion routine). .SPND 
suspends the mainline and allows only completion routines (for I/O and 
mark time requests) to run. .RSUM from one of the completion routines 
resumes the mainline code. These functions enable a program to wait for a 
particular I/O or mark time request by suspending the mainline and having 
the selected event's completion routine issue a .RSUM. This differs from the 
.WAIT request, which suspends the mainline until all I/O operations on a 
specific channel have completed. 

Macro Calls: .SPND 
.RSUM 

Request Formats: 

(.SPND) RO = 
(.RSUM) RO = 

Notes: 

1. The monitor maintains a suspension counter for each job. This counter 
is decremented by .SPND and incremented by .RSUM. A job is sus- 
pended only if this counter is negative. Thus, if a .RSUM is issued 
before a .SPND, the latter request returns immediately. 

2. A program must issue an equal number of .SPND and .RSUM requests. 

3. A .RSUM request from the mainline code increments the suspension 
counter. 

4. A .SPND request from a completion routine decrements the suspension 
counter, but does not suspend the mainline. If a completion routine does 
a .SPND, the mainline continues until it also issues a .SPND, at which 
time it is suspended and requires two .RSUMs to proceed. 

5. Since a .TWAIT is simulated in the monitor using suspend and resume, 
a .RSUM issued from a completion routine without a matching .SPND 
can cause the mainline to continue past a timed wait before the entire 
time interval has elapsed. 

6. A .SPND or .RSUM, like most other programmed requests, can be is- 
sued from within a user-written interrupt service routine if the 
.INTEN/.SYNCH sequence is followed. All notes referring to 
.SPND/.RSUM from a completion routine also apply to this case. 

Errors: 

None. 

Example: 

.TITLE SPND. MAC 

+ 
•SPND/.RSUM- This is an example in the use of the .SPND/.RSUM requests. 
The eKample is a simulation of a mainline Foreground proSram which is 
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; currently suspended waiting for a inessa^e from the BacKdroUndi but which 

1 needs to close a file (perhaps opened by a lENTER ?> before aborting 

i from CTRL-C aotioni A completion routine periodically inspects the CTRL-C 

I status word and resumes the mainline if double CTRL-C is entered^ 

i NOTE: This example MUST be run as a FG Job under an FB monitor. 



START! 
14: 



.MCALL 
.MCALL 

.OSET 
.SCCA 
CALL 
.RCWDC 



.PRINT 
.SPND 
TST 
BNE 



.SCCAi.RCVDC ..EX IT I. PR I NT I 
.OSET i.SPND ..RSUM 



,MRKT 



• QELEIiixl iAllocate another Q-Element 
»MftREAt»SCCA ilnhibit *C*C action by monitor 
CWATCH iStart "watohdos" completion rtne 

• MAREA t«MBUFF i»40. t»MESG iLooK for a fflessaSe 

. !No errors - there's always BG 

. lOther processin<r here... 



•SLEEP 



SCCA 
CLOSE 



i <process messa<re here> 
BR 1* 



iAnnounce we're <fcin<l to suspend 
iSuspend to wait for message 
iWe'ue been .RSUMed . . . 'C"C hit?? 
iBranch if yes 
•otherwise assume messaae came in. 



ILoop. . . 



CWATCH: 

MESG: 

MARK: 

CLOSE: 



OELEM: 

MBUFF: 

MAREA: 

CAREA: 

TIME: 

SCCA: 

ABORT: 
SLEEP: 



TST SCCA iCheok if "C"C entered... 

BEO MARK iBranch if no 

iRSUM !Yesi..waKe up the mainline 

RETURN ithen leaue completion code 

iMRKT "CAREA i»TIME i»CWATCH i»l iSchedule to run aslain in 10 sec. 

RETURN ithen leaue completion code 



.PRINT SABORT 

i <0utput file<s) closed here> 

i 

.EXIT 



.BLKW 
.BLKM 
.BLKW 
.BLKW 
.WORD 
.WORD 

.ASCIZ 
.ASCIZ 

.END 



7 

41 . 

5 

4 

O.GOO. 





{Announce we're abortinsl 
{proceed with "orderly" abort 

iExlt the proSram 

lEx t ra Q-El ement 

iMessasle buffer 

!EMT Argument blocks 

i 

iTime out in 10 seconds 

i'C'C Status word 



/?{ Abort Acknowledged .. .Closing Output File(s) !?/ 
/! Mainline Suspending 1/ 



START 



2.85 .SRESET 

The .SRESET (software reset) request: 

1. Cancels any messages sent by the job. 

2. Waits for all job I/O to complete, which includes waiting for all 
completion routines to run. 

3. Dismisses any device handlers that were brought into memory 
via .FETCH calls. Handlers loaded via the keyboard monitor 
LOAD command remain resident, as does the system device han- 
dler. 

4. Purges any currently open files. Files opened for output with .EN- 
TER are never made permanent. 
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5. Reverts to using only 16(decimal) I/O channels. Any channels 
defined with .CDFN are discarded. A .CDFN must be reissued to 
open more than 16 channels after a .SRESET is performed. 

6. Clears the job's .SPND/.RSUM counter. 

7. Resets the I/O queue to one element. A .QSET request must be 
reissued to allocate extra queue elements. 

8. Cancels all outstanding .MRKT requests. 
SRESET 



Macro Call 
Errors: 

None. 
Example: 



.TITLE 



SRESET. MAC 



.SRESET - This is an exainple in the use of the .SRESET request. 
The example renames a file according to filespecs entered using the 
.CSISPC request. 





.MCALL 


.RENAME ..PRINT. 


.EXIT 






.MCALL 


.CSISPC ..FETCH. 


.SRESET 






ERRBYT 


= 52 




iErro r byte location 


START! 


.CSISPC 


•FILESP ."DEFEXT 




iUse .CSISPC to iet file specs 




.FETCH 


•HANLOD, »FILESP 




SGet Handler from outspec 




BCS 


2$ 




iBranch if failed 




Moy 


"FILESP, R2 




iRZ => Outspec 




MOV 


»FILESP+a6iR3 




iR3 => Inspeo 




MOV 


eR2,FILESP+36 




iCopy deuioB spec to inspeo 




.REPT 


a 




iCopy outspec behind inspec 




MOV 


(R2)+ 1 (R3) + 




!for .RENAME... 




.ENDR 










.RENAME 


»AREA,»0,»FILESP+36 


iRename input file 




BCC 


1* 




iOperaticn successful 




DECB 


@»ERRBYT 




iMaKe error code -1,0 or +1 




BEO 


3» 




iBranch if File-Not-Found 




MOV 


• ILLOP ,R0 




illleaal operation-set up ms3 




BR 


5« 




iBranch to report error 


It: 


.SRESET 
.EXIT 






iOismlss handlers 
iExit program 


Z«) 


MOV 


"NOHAN, RO 




iFetoh failed-set up messase 




BR 


5* 




iBranch to report error 


3$: 


MOV 


•NOFIL.RO 




iFile not found-setup messaSe 


5*1 


.PRINT 






iPrint error messase 




BR 


1* 




iThen exit uia .SRESET 


AREA: 


.BLKW 


5 




!EMT Arsument block 


DEFEXT: 


.WORD 


,0 ,0 ,0 




;Nd default extensions 


NOFILs 


.ASCIZ 


/?File not foun 


d?/ 


iError messaie text 


ILLDP: 


.ASCIZ 


/?Ille3al Operation?/ 




NOHAN: 


.ASCIZ 
.EVEN 


/?. FETCH Failed 


?/ 




FILESP: 


.BLKW 


39. 




iCSISPC Input Area 


HANLOD 


S f 






{Handlers can load here... 



.END 



START 



2.86 .SYNCH (Device Handler and Interrupt Service Routine Only) 

This macro call enables your program to issue programmed requests from 
within an interrupt service routine. Code following the .SYNCH call runs 
at priority level as a completion routine in the issuing job's context. 
Programmed requests issued from interrupt routines are not supported by 
the system and should not be performed unless a .SYNCH is used. 
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.SYNCH, like .INTEN, is not an EMT monitor request, but rather a sub- 
routine call to the monitor. 



Macro Call: 
where: 

area 



pic 



.SYNCH area[,pic] 



is the address of a seven-word block that you must set aside 
for use by .SYNCH. This argument, area, represents a special 
seven-word block used by .SYNCH as a queue element. This 
is not the same as the regular area argument used by many 
other programmed requests. The user must not confuse the 
two; he should set up a unique seven-word block specifically 
for the .SYNCH request. The seven-word block appears as: 

Word 1 RT-11 maintains this word; its contents should not 
be altered by the user 

2 The current job's number. This must be set up by 
the user program. It can be obtained by a .GTJB 
call or from the I/O queue element in a device han- 
dler 

3 Unused 

4 Unused 

5 RO argument. When a successful return is made 
from .SYNCH, RO contains this argument 

6 Must be -1 

7 Must be 

is an optional argument that, if non-blank, causes the 
.SYNCH macro to produce position-independent code for use 
by device drivers 



Note: 



.SYNCH assumes that the user has not pushed anything on the stack 
between the .INTEN and .SYNCH calls. This rule must be observed 
for proper operation. 



Errors: 



The monitor returns to the location immediately following the 
.SYNCH if the .SYNCH was rejected. The routine is still unable to 
issue programmed requests, and R4 and R5 are available for use. An 
error is returned if another .SYNCH that specified the same seven- 
word block is still pending. 

NOTE 

The monitor dismisses the interrupt without returning to the 
.SYNCH routine if one of the following conditions occur: 

1. You specified an illegal job number. 

2. The job number does not exist (for example, you specify 2, 
and there is no foreground job). 

3. The job is exited or terminated with an .EXIT pro- 
grammed request. 
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You can find out if the block is in use by: 

1. Checking location Q.COMP (offset 14 octal). If this location con- 
tains a zero, the block is available. 

2. Performing a .SYNCH call. If the block is busy, an error return 
will be performed. 

Normal return is to the word after the error return. At this point, the 
routine is in user state and is thus allowed to issue programmed 
requests. RO contains the argument that was in word 5 of the block. 
RO and Rl are free for use without having to be saved. R4 and R5 are 
not free, and do not contain the same information they contained 
before the .SYNCH request. A long time can elapse before the pro- 
gram returns from a .SYNCH request since all interrupts must be 
serviced before the main program can continue. Exit from the routine 
should be done via an RTS PC. 



Example: 



.TITLE SYNCH. MAC 



.SYNCH - This is an example of the .SYNCH request. 

The example is a sKeleton of a prosram which could input data 

from the outside world by means of an in-line interrupt seruioe routinei 

buffer it until a whole block's worth has been input) then use 

a .MRITE request to store the data on an RT-11 deuioe. 





.MCflLL 


■ GTJB. .INTEN. .WRITE. 


.WAIT (.SYNCH ,, EX IT). PR I NT 


START; 


MOV 


• JOB ,R5 




iResults of ,GTJB 30 here 




.GTJB 


•tAREA.RS 




iGet Job number (either FG or BG) 




Moy 


(R5) .SYNBLK + 2 


iStore Job number in .SYNCH block 




i 


< 




iHere we open an RT-11 output 




5 


. 




ideuice. then initiate input from 




i 


• 




ia "foreisn" deuioe. interrupts to 




i 


♦ 




ibe handled by our in-line interrupt 




i 


. 




iseruice routine.... 


INTRPT: 








ilNTERRUPT SERVICE ROUTINE 




.INTEN 

i 

i 
i 


5 




.Notify RT-11 and drop to priority 5 
iProoess interrupt and buffer input 
iTime to write a buffer - switch 
.buffers (should be double buffered 
ISO that interrupt processins can 
.continue durina write operation). 




.SYNCH 


•SYNBLK 




!Do a .SYNCH so we can use a .WRITE 




BR 


SYNFAIL 




!Return here if a .SYNCH block in use 
.Return here if oKay . , . 




.WAIT 


• 1 




iSee if error on last write 




BCS 


WRFAIL 




.Branch if there was 




WRITE 


• AREA.sl 


DBUFF.^25S. 


.BLK 

iOueue a write to store the data 




INC 


BLK 




iand bump the block number. 




RETURN 






!Re-enable interrupts and leaMe 


SYNBLK: 


.WORD 







i. SYNCH block 




.WORD 







•Job number soes here 




.WORD 







iNext two words reserved 




.WORD 







. 




.WORD 


5 




iRO contains 5 on successful .SYNCH 




.WORD 


-1 .0 




.Required ualues for the Monitor 
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SYNFAIL! 


i 


• 


WRFAIL: 


! 
MOV 


SWERR.RO 


ERRM: 


.PRINT 
.EXIT 




BLKs 


.WORD 





AREA: 


.BLKM 


5 


JOB; 


.BLKW 


B. 


OBUFF! 


.MORD 





IBUFF: 


.WORD 





BUFFI ! 


.BLKM 


256. 


BUFFZ: 


.BLKW 


256. 


WERR: 


.ASCIZ 


/?Write Error?/ 


SYNERR: 


.ASCIZ 
.EVEN 


/7SYNCH Failed?/ 



i. SYNCH failed. . . 
•This can be a problem if the 
)ne»t interrupt came in before the 
fbuffer was written out! 

iRO — » error messase text 
lOutPut the error message 
i then exit. 

iBlocK number to urite 

lEMT Argument blooK 

iArea for .GTJB data 

iPointer to current output buffer 

JPointer to current input buffer 

iBuffer 1 

(Buffer 2 



END 



START 



2.87 .TIMIO (Device Handler Only) 

The .TIMIO macro issues the device time-out call in the handler I/O initia- 
tion section. This request schedules a completion routine to run after the 
specified time interval has elapsed. The completion routine runs in the 
context of the job indicated in the timer block. In XM systems, the comple- 
tion routine executes with kernel mapping, since it is still a part of the 
interrupt service routine. (See the RT-11 Software Support Manual for 
more information about interrupt service routines and the XM monitor.) As 
usual with completion routines, RO and Rl are available for use. When the 
completion routine is entered, RO contains the sequence number of the 
request that timed out. 

Macro Call: .TIMIO tbk,hi,lo 



where: 



hi 
lo 
Example: 



tbk is the address of the timer block, a seven-word pseudo timer 
queue element. (The timer block format is shown in Table 2—1 
under the .CTIMIO request.) You must set up the address of 
the completion routine in the seventh word of the timer block 
in a position-independent manner 

is the high-order word of a two- word time interval 

is the low-order word of a two- word time interval 



.TITLE TIMID. MAC 

i + 

i TIMIO. MAC - This is an example of a simplei RT-11 deuioe driueri 
i to illustrate the use of the .TIMIO/ . CTIMIO requests. The timeout 
! completion routine will be entered if a character hasn't been 
! successfully transmitted in 1/10 sec (approx. 110 baud). In this 
i example the completion routine takes no explicit action! the fact 
i that the timeout occurred is enaush to be considered a "hard" error. 
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. MCALL 



. DRBEG i.DRAST cDRFIN . . DREND . , OELDF ,.TIMIO..CTIMIO 



.IIF NDF MMG*T. MMG«T=0 
. IIF NDF ERL*Gi ERL«G = 
, IIF NDF TIM*IT . TIM«IT = 



{Define these in case nat 
tassembled with SYSCND.MAC 



.IIF NDF BPtVECi SP«yEC=304 
.IIF NDF SP«CSR. SPtCSR=17650a 
.IIF NDF SPtPRI t SPtPRI=a 





lOERR = 


1 




SPSTS = 


20000 




SPSIZ = 







TIME = B 




COD = 377 




.OELDF 






.DRBEG 


SP.SP*yEC, SPSIZ, SPSTS 




Moy 


SPCOE.Rfl 




ASL 


0*WCNT(Ra) 




BCC 


SPERR 




BEO 


SPDUN 


SPRET: 


Moy 


PC.R5 




ADD 


•SPTOUT- . .R5 




Moy 


R5.TBLK+ia 




.TIMIO 


TBLK lO.TIME 




BIS 


•100ie»SP»CSR 




RETURN 




i INTERRUPT SERVICE ROUTINE 




.DRAST 


SP.SPiPRI 




Moy 


SPCOE.Ra 




TST 


e«sp»csR 




BMI 


SPRET 




TSTB 


e«sptcsR 




BPL 


SPRET 




.CTIMIO 


TBLK 




BCS 


SPERR 




MOVB 


eO*BUFF(R4) ,eBSP*CSR + Z 




INC 


0*BUFF(R4) 




INC 


0»WCNT(Rd) 




BEO 


SPDUN 




BR 


SPRET 


SPTOUT: 


i 
RETURN 


• 


SPERR: 


BIS 


»I0ERR,I5Q$CSW(R4) 


SPDUN: 


.DRFIN 


SP 


TBLK: 


.WORD 


0. TIME. 0,0 ,177000 + COO, 




.DREND 


SP 




.END 





iDefine default ueotor 
iDefine default CSR addr 
iDefine default deuice priority 

iHard I/O error bit definition 
SDevice Status = Urite only 
iDeuioe Size == tChar deuice) 
iTimeout Interval = 1/10 sec 
iDeuice i.d. code 

iUse .OELDF to define O-Elerti offsets 

iBeiin driuer code with .DRBEG 

ina => Current O-Element 

iMaKe word count byte count 

iA read from a write/only deuice? 

iZero word count. ..Just exit 

(Calculate PIC address 

fCOMPletion routine 

SMoue it to arSument blocK 

{Schedule a MarKtime 

lEnable OL-11 interrupt 

SReturn to monitor 



;Use .DRAST to define Int Svc Sect. 

iRH => 0-Element 

!Er ro r? 

iVes . . . 'hans ' until ready 

i Is device ready? 

iNo...io wait 'till it is 

{Cancel completion routine 

iToo late - it timed out! 

iXfer byte frow buffer to DL-11 

iBuMP the buffer pointer 

land the word count (it's neJatiue!) 

{Branch if done 

{Go wait 'till char »mitted 

{Timeout completion routine 

{In this example, it does nothing. 

{In real life it may want to try 

{to taKe some corrective action... 

{Set error bit in CSW 

{Use .DRFIN to return to Monitor 



{Use .DREND to end code 



2.88 TLOCK 



The .TLOCK (test lock) request is used in an FB environment to attempt to 
gain ownership of the USR. It is similar to .LOCK in that, if successful, the 
user job returns with the USR in memory (it is identical to .LOCK in the SJ 
monitor). However, if a job attempts to .LOCK the USR while another job is 
using it, the requesting job is suspended until the USR is free. With 
.TLOCK, if the USR is not available, control returns immediately with the 
C bit set to indicate the .LOCK request failed. 
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Macro Call: .TLOCK 
Request Format: 

RO = 
Errors: 

Code 

Example: 

.TITLE TLOCK. MAC 



Explanation 

USR is already in use by another job. 



.TLOCK - This is an eKaidPle in the use of the .TLOCK request. 
In this exatiiplet the user proSrani needs the USR for a sub-Job it is 
executing. If it fails to set the USR it "suspends" that sub-Job and 
runs another sub-Job (that perhaps doesn't need the USR for execution). 
This type of prooedure is useful to schedule seueral sub-Jobs within 
a single bacKSround or foreground program. 





.MCALL 


.TLOCK (.LOOKUP. .UN 


START: 


.TLOCK 






BCS 


SUSPND 




.LOOKUP 


»AREA.«4,«FILE 




BCS 


LKERR 




i 

.PRINT 


•JIMSG 




.UNLOCK 






TSTB 


JZSW 




BNE 


1« 




CALL 


J0B2 


1$! 


.EXIT 




SUSPNDs 








TSTB 


JZSW 




BNE 


START 




JSR 


PC .JOBZ 




INC 


JZSW 




BR 


START 


AREA: 


.BLKM 


5 


FILE: 


.RAD50 


/DK/ 




.RAD50 


/OUFILE/ 




.RAD50 


/TMP/ 


LKERR: 


.PRINT 
.EXIT 


•LKMSG 


LKMSG: 


.ASCIZ 


/?FiIe Not Found?/ 


JltlSG; 


.ASCIZ 


/Job •! Executed/ 


J2MSG! 


.ASCIZ 


/Job »2 Executed/ 


J2SM: 


.BYTE 
.EUEN 





JOBZ! 


.PRINT 


•JZMSG 




RTS 


PC 



Besin Mainline proSram 

Try to set the USR for 1st "Job" 

Fai led ... b ranch to "suspend" 1st Job 

Succeeded. ..proceed with 1st Job 

Branch if error on LOOKUP 

1st Job inuolues file processinS...do 

Tell user we executed... 

1st Job f inished . I . release USR 

ChecK if we ran Job »2 while USR busy 

Yup - we did 

Nope - do it now 



i" Suspend" current "Job" 

iOid we already run Job *2 

lYes - don't do it aSain 

i"Run" other "Job" 

iSet switch that says we ran Job »2 

iWhen it's finished, try 1st Job aSain 



it ! 



iEMT arSufrtent block 
!File spec for Job «1 



iError on .LOOKUP 



Report it! 



iSuitoh to control Job »2 execution 



iZnd "Job" - Doesn't need USR 
•Return when done 



.END 



START 



2.89 .TRPSET 



.TRPSET allows the user job to intercept traps to 4 and 10 instead of having 
the job aborted with a ?MON-F-Trap to 4 or ?MON-F-Trap to 10 message. 
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If .TRPSET is in effect when an error trap occurs, the user-specified routine 
is entered. The status of the carry bit on entry to the routine determines 
which trap occurred: carry bit clear indicates a trap to 4; carry bit set 
indicates a trap to 10. The user routine should exit with an RTI instruction. 
Traps to 4 can also be caused by user stack overflow on some processors 
(check your processor handbook). These traps are not intercepted by the 
.TRPSET request, but they do cause job abort and a printout of the message 
?MON-FStack overflow in the SJ monitor or ?MON-F-Trap to 4 in the FB 
and XM monitors (see the RT—11 System Message Manual). 

Macro Call: .TRPSET area,addr 

where: 

area is the address of a two- word EMT argument block 

addr is the address of the user's trap routine. If an address of is 
specified, trap interception is disabled 

Request Format: 

RO -^ area: 



addr 



Notes: 



Reissue a .TRPSET request whenever an error trap occurs and the user 
routine is entered. The monitor disables user trap interception prior to 
entering the user trap routine. Thus, if a trap should occur from within 
the user's trap routine, an error message is generated and the job is 
aborted. The last operation the user routine should perform before an 
RTI is to reissue the .TRPSET request. 

In the XM monitor, traps dispatched to a user program by .TRPSET 
execute in user mode. They appear as interrupts of the user program by 
a synchronous trap operation. Programs that intercept error traps by 
trying to steal the trap vectors must be carefully designed to handle two 
cases accurately: programs that are virtual jobs and programs that are 
privileged jobs. 

If the program is a virtual job, the stolen vector is in user virtual space 
that is not mapped to kernel vector space. The proper method is to use 
.TRPSET; otherwise interception attempts fail and the monitor contin- 
ues to handle traps to 4 and 10. 

If the program is a privileged job, it is mapped to the kernel vector 
page. The user can steal the error trap vectors from the monitor, but 
the benefits of doing so must be carefully evaluated in each case. Trap 
routines run in the mapping mode specified by bits 14 and 15 of the trap 
vector PS word. With both bits set to 0, kernel mode is set. However, 
kernel mapping is not always equivalent to user mapping, particularly 
when extended memory is being used. With both bits 14 and 15 of the 
PS set to 1, user mode is set, and the trap routine executes in user 
mapping. 
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Errors: 

None. 
Example: 

.TITLE TRPSET.MftC 



.TRPSET - This is an eKaitiPle in the use of the .TRPSET request. 
In this example a user trap routine is set i then deliberate 
traps to a & 10 are caused (not uery practical but it demonstrates 
that .TRPSET really worKs!). 





.MCALL 


.TRPSET. .EXIT. 




Diyz = 87 




START: 


.TRPSET 


»AREA.«TRPLOC 




Diyz 






TST 


islGBBBB 




.EXIT 




TRPLDC: 








BCS 


1$ 




.PRINT 


«TRP4 




BR 


2* 


1$: 


.PRINT 


BTRPIO 




.TRPSET 


«AREA(«TRPLOC 


2»: 


RTI 




AREA: 


.WORD 


0,0 


TRP4: 


.ASCIZ 


/?Trap to a?/ 


TRPIO: 


.ASCIZ 


/?Trap to 10?/ 



iDiuide by zero - illeSal instruction 

iBe Sin example 

(Set UP a trap routine to handle traps 

ito a & 10. . . 

illleSal instruction - Trap to 10 

SAddress non-existent memory - Trap to 

iExi t pros ram 

!Trap routine 

iC bit set = TRAP 10 

iRepo rt T rap to a 

iBranch to reset trap routine 

iRePD rt t rap to 10 

(Reset trap routine address 

iReturn to offendinS code 

iEMT arsument blooK 
;E r ro r messages .. • 



,END START 

2.90 .TTYIN/.TTINR 



The requests .TTYIN and .TTINR transfer a character from the console 
terminal to the user program. The character thus obtained appears right- 
justified (even byte) in RO. The user can cause the characters to be returned 
in RO only, or in RO and other locations. 

The expansion of .TTYIN is: 

EMT 340 
BCS .-2 

The expansion of .TTINR is: 

EMT 340 

If no characters or lines are available when an EMT 340 is executed, return 
is made with the carry bit set. The implication of these calls is that .TTYIN 
causes a tight loop waiting for a character/line to appear, while the user 
can either wait or continue processing using .TTINR. 

If the carry bit is set when execution of the .TTINR request is completed, it 
indicates that no character was available; the user has not yet typed a valid 
line. Under the FB or XM monitor, .TTINR does not return the carry bit set 
unless bit 6 of the Job Status Word (JSW) was on when the request was 
issued. 
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There are two modes of doing console terminal input. The choice is gov- 
erned by bit 12 of the job status word. If bit 12 is 0, normal I/O is performed. 
In this mode, the following conditions apply: 

1. The monitor echoes all characters typed. 

2. CTRL/U and the DELETE key perform line deletion and charac- 
ter deletion, respectively. 

3. A carriage return, line feed, CTRL/Z, or CTRL/C must be struck 
before characters on the current line are available to the pro- 
gram. When one of these is typed, characters on the line typed are 
passed one by one to the user program. 

If bit 12 is 1, the console is in special mode. The effects are: 

1. The monitor does not echo characters typed except for CTRL/C 
and CTRL/0. 

2. CTRL/U and the DELETE key do not perform special functions. 

3. Characters are immediately available to the program. 

In special mode, the user program must echo the characters received. How- 
ever, CTRL/C and CTRL/0 are acted on by the monitor in the usual way. 
Bit 12 in the JSW must be set by the user program. This bit is cleared when 
the program terminates. 

Regardless of the setting of bit 12, when a carriage return is entered, both 
carriage return and line feed characters are passed to the program; if Ibit 12 
is 0, these characters will be echoed. 

Lowercase conversion is determined by the setting of bit 14 in the JSW. If 
bit 14 is 0, lowercase characters are converted to uppercase before being 
echoed (if bit 12 is 0) and passed to a program; if bit 14 is 1, lowercase 
characters are echoed (if bit 12 is 0) and passed as received. Bit 14 is 
cleared when the program terminates. 

CTRL/F and CTRL/B (and CTRL/X in system job monitors) are not affected 
by the setting of bit 12. The monitor always acts on these characters (unless 
the SET TT NOFB command is issued). 

CTRL/S and CTRL/Q are intercepted by the monitor (unless, under the FB 
or XM monitor, the SET TT NOPAGE command is issued). 

Under the FB or XM monitor, if a terminal input request is made and no 
character is available, job execution is blocked until a character is ready. 
This is true for both .TTYIN and .TTINR, and for both normal and special 
modes. If a program requires execution to continue and the carry bit to be 
returned, it must set bit 6 of the Job Status Word before the .TTINR re- 
quest. Bit 6 is cleared when a program terminates. 

If the single-line editor has been enabled by the commands SET SL ON and 
SET SL TTYIN, and if bits 4 and 12 of the JSW are 0, input from a .TTYIN 
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or .TTINR request will be edited by SL. If either bit 4 or bit 12 is set, SL 
will not edit input. If SL is editing input, the state of bit 6 (inhibit TT wait) 
is ignored and a .TTINR request will not return until an edited line is 
available. 

NOTE 

The .TTYIN request does not get characters from indirect 
files. If this function is desired, the .GTLIN request must be 
used. 

Macro Calls: .TTYIN char 
.TTINR 

where: 

char is the location where the character in RO is to be stored. If 
char is specified, the character is in both RO and the address 
represented by char. If char is not specified, the character is 
inRO 

Errors: 

Code Explanation 

No characters available in ring buffer. 
Example: 

Refer to the example following the description of 
.TTYOUT/.TTOUTR. 



2.91 .TTYOUT/.TTOUTR 



The requests .TTYOUT and .TTOUTR cause a character to be transmitted 
to the console terminal. The difference between the two requests, as in the 
.TTYIN/.TTINR requests, is that if there is no room for the character in the 
monitor's buffer, the .TTYOUT request waits for room before proceeding, 
while the .TTOUTR does not wait for room and the character is not output. 

If the carry bit is set when execution of the .TTOUTR request is completed, 
it indicates that there is no room in the buffer and that no character was 
output. Under the FB or XM monitor, .TTOUTR normally does not return 
the carry bit set. Instead, the job is blocked until room is available in the 
output buffer. If a job requires execution to continue and the carry bit to be 
returned, it must turn on bit 6 of the Job Status Word before issuing the 
request. 

The .TTINR and .TTOUTR requests have been supplied to help those users 
who want to continue rather than suspend program execution until a con- 
sole operation is complete. With these modes of I/O, if a no-character or no- 
room condition occurs, the user program can continue processing and try 
the operation again at a later time. 
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NOTE 



If a foreground job leaves bit 6 set in the Job Status Word, 
any further foreground .TTYIN or .TTYOUT requests cause 
the system to lock out the background until a character is 
available. Note also that each job in the foreground/back- 
ground environment has its own Job Status Word, and there- 
fore can be in different terminal modes independently of the 
other job. 



Macro Call: 



where: 



char 



.TTYOUT char 
.TTOUTR 



is the location containing the character to be loaded in RO and 
printed. If not specified, the character in RO is printed. Upon 
return from the request, RO still contains the character 



Errors: 



Code Explanation 

Output ring buffer full. 
Example: 

.TITLE TTYIN. MAC 



. TTYIN / .TTYOUT - This is an example in the use of the .TTYIN 
& .TTYOUT requests. The example accepts a line of input from the 
console keyboard, then echoes it on the terminal. Usina .TTYIN & 
.TTYOUT requests illustrate Synchronous terminal I/Oi i.e.. the 
Monitor retains control (the Job is blocKed) until the requests 
are satisfied. 





.MCALL 


.TTYIN ..TTYOUT 


START: 


MOV 


• BUFFER ,R1 




CLR 


R2 


INLOOP: 


.TTYIN 


(Rl) + 




INC 


R2 




CMPB 


• 12. RO 




BNE 


INLOOP 




Moy 


• BUFFER iRl 


DUTLOOP: 


•TTYOUT 


(Rl) + 




DEC 


R2 




BEO 


START 




BR 


OUTLOOP 


BUFFER: 


.BLKU 


ea. 




.END 


START 




.TITLE 


TTINR.MAC 



iRl => Character buffer 

iClear character count 

iRead char into buffer 

iBufflp count 

iWas last char a LF ? 

iNo...«et next character 

iYes.. .point Rl to besinnins of buffer 

iPrint a cha racte r 

iDecrease count... 

iDone if count = 

SLoop to print another character 

iCharaoter buffer... 



.TTINR / .TTOUTR - This is an example in the use of the .TTINR & 
.TTOUTR requests. Like TTYIN. MAC. this example accepts lines of 
input from the console Keyboard, then echoes it on the terminal. 
But rather than uaitins for the user to type somethins at 'INLOOP' 
or wait for the output buffer to have available space at 'OUTLOOP' 
the routine has been receded usin* .TTINR and .TTOUTR to allow 
other prooessins to be carried out if a uait condition is reached. 
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.MCALL 


.TTYIN,.TTY 




.MCALL 


.TTINR i.TTO 




JSW = ati 




START; 


MOV 


•BUFFER iRl 




CLR 


R2 




BIS 


«100>e«JSU 


INLODP: 


.TTINR 






BCS 


NOCHAR 


CHRIN: 


MOVB 


R0,(R1) + 




INC 


R2 




CMPB 


R0.»12 




BNE 


INLOOP 




Moy 


aBUFFERiRl 


OUTLOOP! 


MOVB 
.TTOUTR 


(Rl) iRO 




BCS 


NOROOM 


CHROUT: 


DEC 


RZ 




BEO 


START 




INC 


Rl 




BR 


OUTLOOP 


NDCHAR: 


, TTINR 






BCC 

; 


CHRIN 




i 

BR 


NOCHAR 


NOROOM: 








MOVE 


(Rl ) iRO 




.TTOUTR 






BCC 
i 


CHROUT 




i 

i 
BIC 


»100.e«JSW 




.TTYOUT 


(Rl ) 




BIS 


•100i@«JSW 




BR 


CHROUT 


BUFFER: 


.BLKW 


64. 




■ END 


START 



iLocation of Job Status Word in SYSCOM 

iPolnt Rl to buf f e r 

iClcar character count 

iSet bit «G in JSW so .TTINR/ . TTOUTR will 

ireturn C bit set if no char/no room... 

iGet char from terminal 

iNone auailablB 

iPut char in buffer 

{Increase caunt 

iWas last char = LF? 

iNo ...set next char 

iYes.. .point Rl to besinnins of buffer 

iPut char in RO 

iTry to print it 

iBranch if no room in output buffer 

iOecrease count 

iDone if count =0 

!Bump buffer pointer 

ithen branch to print next char 

iComes here if no char auail 

itry to asain to aet one 

iThere's one auail this time! 

i 

iOo other processing 

(Try again 

iComes here if no room in buffer 

iPut char in RO 

iTry to print it asain 

{Successful ! 

iCode to be executed while waiting 

i 

iNow we must hans to wait... 

iClear bit »G in JSW 

iUse .TTYOUT to wait for rocw 

iFinally successful - reset bit »G 

ithen return to output loop 

iBuf f e r 
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The .TWAIT request suspends the user's job for an indicated length of time. 
.TWAIT requires a queue element and thus should be considered when the 
.QSET request is issued. 

Macro Call: .TWAIT area,time 

where: 

area is the address of a two-word EMT argument block 

time is a pointer to two words of time (high order first, low order 
second), expressed in ticks 

Request Format: 
RO — * area: 



24 



time 
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Notes: 

1. Since a .TWAIT is simulated in the monitor using suspend and resume, 
a .RSUM issued from a completion routine without a matching .SPND 
can cause the mainstream to continue past a timed wait before the 
entire time interval has elapsed. In addition, a .TWAIT issued within a 
completion routine is ignored by the monitor, since it would block the 
job from ever running again. 

2. The unit of time for this request is clock ticks, which can be 50 Hz or 60 
Hz, depending on the local power supply, if your system has a line 
frequency clock. This must be kept in mind when the time interval is 
specified. 

Errors: 

Code Explanation 

No queue element was available. 
Example: 

.TITLE TWAIT. MAC 

i + 

i .TWAIT - This is an example in the use of the .TWAIT request. 

) .TWAIT is useful in applications where a prosram must be only 

i activated periodically. This example uill 'wake up' every flue seconds 

i to perform a simulated "tasK"i and then 'sleep' asain. (For example 

; purposes this cycle will be repeated for a maximum of about 35 see). 



START! 
1$: 



TASK: 



It: 



NDO: 

AREA: 
TIME: 
COUNT: 
TCNTi 

TICK: 
TOCK: 
BYE: 
OERR: 



.MCALL 

CALL 

.TWAIT 

BCS 

CALL 

DEC 

BNE 

.PRINT 

.EXIT 

INC 

BIT 

BEQ 

.PRINT 

RETURN 

.PRINT 

RETURN 

.PRINT 

.EXIT 

.WORD 

.WORD 

.WORD 

.WORD 

.ASCII 
.ASCIZ 
.ASCIZ 
.ASCIZ 
.END 



.TWAIT..OSET1.EXIT ..PRINT 



TASK 

•AREA,«TIME 

NOO 

TASK 

COUNT 

1* 

• BYE 



TCNT 

• 1 .TCNT 
1$ 

• TICK 



• TOCK 

• OERR 

0.0 

.GO. *5. 

7 




Pe rf rm tasK . . . 

Go to sleep for 5 seconds 

Branch if no queue element 

Perform tasK asain 

Bump counter - example Socd for 35 see 

Branch if time's not up 

Say we ' re th ru 

Exit pro9 ram 

Periodic task simulated here 

Bump a counter 

Is it odd? 

Branch if not 

Odd counter prints "tioK..." 

Return to caller 

Euen counter prints "took" 

Return to caller 

iPrint error message 

lExi t pros ram 

iEMT Argument block 

<60 ticks/sec « 5 seconds 

iMaxifflum cycles for example 

iTick.tock count 



/Tick. . ./<200> 

/Took/ 

/Example Concluded/ 

/?No O-Element Available?/ 

START 



.Message text 



2.93 .UNLOCK 

See .LOCK/.UNLOCK (Section 2.41). 
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2.94 .UNMAP (XM Only) 



The .UNMAP request unmaps a window and flags that portion of the pro- 
gram's virtual address space as being inaccessible. When an unmap opera- 
tion is performed for a virtual job, attempts to access the unmapped address 
space cause a memory management fault. For a privileged job, the default 
(kernel) mapping is restored when a window is unmapped. 

Macro Call: .UNMAP area,addr 

where: 

area is the address of a two- word argument block 

addr is the address of the window control block that describes the 
window to be unmapped 

Request Format: 



RO -^ area: 



36 



addr 



Errors: 

Code Explanation 

3 An illegal window identifier was specified. 
5 The specified window was not already mapped. 
Example: 

Refer to the example following the description of .CRAW. 

2.95 .UNPROTECT 

See .PROTECT/.UNPROTECT (Section 2.60). 

2.96 .WAIT 

The .WAIT request suspends program execution until all input/output re- 
quests on the specified channel are completed. The .WAIT request, com- 
bined with the .READ/.WRITE requests, makes double buffering a simple 
process. 

.WAIT also conveys information through its error returns. An error is re- 
turned if either the channel is not open or the last I/O operation resulted in 
a hardware error. 

If an asynchronous operation on a channel results in end-of-file, the follow- 
ing .WAIT programmed request will not detect it. The .WAIT request de- 
tects only hard error conditions. A subsequent operation on that channel 
will detect end-of-file and will return to the user immediately with the 
carry bit set and the end-of-file code in byte 52. Under these conditions, the 
subsequent operation is not initiated. 
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In an FB system, executing a .WAIT when I/O is pending causes that job to 
be suspended and another job to run, if possible. 

Macro Call: .WAIT chan 

Request Format: 

RO = 



chan 



Errors: 



Code Explanation 

Channel specified is not open. 
1 



Hardware error occurred on the previous I/O operation on 
this channel. 



Example: 



.TITLE WAIT. MAC 

h 

.WAIT - This is an example in the use of the .WAIT request. The 
example defflonst rates asynchronous I/O where a mainline prodram 
initiates input uia .READ re<iuestsi does some other processing) 
maKes sure input has completed uia the .WAIT re^iuesti then out- 
puts the blocK Just read. Another .WAIT is issued before the next 
read is issued to maKe sure the preuious write has finished. This 
example is a single file copy prosrami utilizing .CSIGEN to input 
the file speosi load the re<iuired handlers and open the files. 





.MCALL 


.READ. .WRITE ..C 




.MCALL 


.CSIGEN, .EXIT,. 




ERRBYT 


= 52 




.ENABL 


LSB 


START: 


.CSIGEN 


«DSPACE,»DEFEXT 




MOV 


•AREA,R5 


1«: 


.READ 


R5,i>3 




BCS 


G» 




BIT 


■ 1 iIOBLK 




BNE 


2$ 




.PRINT 


DMESSG 


Z»: 


.WAIT 


• 3 




BCS 


5* 




.WRITE 


R5,»0 




BCS 


3$ 




i 
INC 


lOBLK 




.WAIT 


»0 




BCC 


1* 


3t: 


Moy 


•WRERR.RO 


4t! 


.PRINT 
.EXIT 




5$: 


MQy 


«RDERR,RO 




BR 


at 


G*: 


TSTB 


e»ERRBYT 




BNE 


54 




.PRINT 


• DONE 




.CLOSE 


»0 




.SRESET 






.EXIT 




AREA: : 


.WORD 






iError Byte location in SYSCOM 

■Enable local symbol block 

iUse CSIGEN to Set handlers, files 

iR5 => EMT Arsument list 

iRead a blocK . . . 

iBranch on error 

)Then simulate 

!some other 

imeanin 3f ul ( ?) process... 

iDid read finish OK? 

iBranch if not 

iNou write the block Just read 

iB ranch on error 

iCould do some more processing here. 

Bump block • for next read 

Wait for write to finish 

Branch if successful 

RO => Write error mss 

Report error 

then exit pros ram 

RO = > Read error ms 9 

Branch to report error 

Read error.. .EOF? 

Branch if not 

Yes ... announce completion 

Make output file permanent 

Dismiss fetched handlers 

then exit prosf ram 

EMT Area block 
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IQBLKs 


.MORD 




.MORD 




.HORD 




.WORD 


BUFF: 


.BLKM 


DEFEXT: 


,MORD 


DONE: 


.ASCIZ 


MESSG: 


.flSCIZ 


WRERR! 


.flSCIZ 


RDERRs 


.flSCIZ 


EOF: 


.BYTE 




• EVEN 


DSPACE 


= , 



BlocK «i 

Buffer addr & word oaunt 

already fixed in blooK... 





BUFF 

Z5S. 



Z5G. iI/0 buffer 

O.OiO.O iNo default extensions 

/I-O Transfer Complete/ iMessaSes . . . 

<15><12>/< Simulating Mainline Praoes5in9 >/ 

/?WritB Error?/ 

/?Read Error?/ 

'EOF flas 



for CSIGEN 



■Handlers may be loaded starting here 



.END 



START 



2.97 .WDBBK (XM Only) 



The .WDBBK macro defines symbols for the window definition block and 
reserves space for it. Information provided to the arguments of this macro 
permits the creation and mapping of a window through the use of the 
.CRAW request. Note that .WDBBK automatically invokes .WDBDF. 

Macro Call: .WDBBK wnapr,wnsiz[,wnrid,wnoff,wnlen,wnsts] 
where: 

wnapr is the number of the Active Page Register set that includes 
the window's base address. A window must start on a 4K- 
word boundary. The valid range of values is from through 
7 

wnsiz is the size of this window (expressed in 32-word units) 

wnrid is the identification for the region to which this window 
maps. This argument is optional; supply it if you need to 
map this window. Use the value of R.GID from the region 
definition block for this argument after you create the re- 
gion to which this window must map 

wnoff is the offset into the region at which to start mapping this 
window (expressed in 32- word units). This argument is op- 
tional; supply it if you need to map this window. The default 
is 0, which means that the window starts mapping at the 
region's base address 

wnlen is the amount of this window to map (expressed in 32-word 
units). This argument is optional; supply it if you need to 
map this window. The default value is 0, which maps as 
much of the window as possible 

wnsts is the window status word. This argument is optional; sup- 
ply it if you need to map this window when you issue the 
.CRAW request. Set bit 8, called WS.MAP, to cause .CRAW 
to perform an implied mapping operation 

Example: 

See Chapter 4 of the RT-11 Software Support Manual for an example 
that uses the .WDBBK macro and a detailed description of the ex- 
tended memory feature. 
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2.98 .WDBDF (XM Only) 

The .WDBDF macro defines the symbolic offset names for the window defi- 
nition block and the names for the window status word bit patterns. In 
addition, this macro also defines the length of the window definition block 
by setting up the following symbol: 

W.NLGH = 16 

The .WDBDF macro does not reserve any space for the window definition 
block (see .WDBBK). 

Macro Call: .WDBDF 

The .WDBDF macro expands as follows: 

W.NID = 

W.NAPR = 1 

W.NBAS = 2 

W.NSIZ = 4 

W.NRID = 6 

W.NOFF = 10 

W.NLEN = 12 

W.NSTS = 14 

W.NLGH = 16 

WS.CRW = 100000 

WS.UNM - 40000 

WS.ELW = 20000 

WS.MAP = 400 

2.99 .WRITE/.WRITC/.WRITW 

Write operations for the three modes of RT-11 I/O are done using the 
.WRITE, .WRITC, and .WRITW programmed requests. 

Note that in the case of .WRITE and .WRITC, additional queue elements 
should be allocated for buffered I/O operations (see .QSET programmed 
request). 

Under an FB monitor with the system job feature, .WRITE/C/W requests 
may be used to send messages to other jobs in the system. 

.WRITE 

The .WRITE request transfers a specified number of words from memory to 
the specified channel. Control returns to your program immediately after 
the request is queued. 

Macro Call: .WRITE area,chan,buf,wcnt,blk 
where: 

area is the address of a five-word EMT argument block 
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chan 
buf 
went 
blk 



is a channel number in the range to 376(octal) 

is the address of the memory buffer to be used for output 

is the number of words to be written 

is the block number to be written. For a file-structured 
.LOOKUP or .ENTER, the block number is relative to the 
start of the file. For a non-file-structured .LOOKUP or .EN- 
TER, the block number is the absolute block number on the 
device. The user program should normally update blk before 
it is used again. Some devices, such as LP, may assign the blk 
argument special meaning. For example, if blk = 0, LP: is- 
sues a form feed 



Request Format: 
RO -^ area: 



U<1\'^ 



11 



chan 



blk 



buf 



went 



NOTE 

When any .WRITE, .WRITC, or .WRITW programmed re- 
quest is returned, RO contains the number of words requested 
if the write is to a sequential-access device (for example, 
magtape). If the write is to a random-access device (disk or 
DECtape), RO contains the number of words that will be writ- 
ten (.WRITE or .WRITC) or have been written (.WRITW). If a 
request is made to write past the end-of-file on a random- 
access device, the word count is shortened and an error is 
returned. The shortened word count is returned in RO. If a 
write goes past EOT on magtape, an error is returned and 
RO = 0. Note that the write is done and a completion routine, 
if specified, is entered, unless the request cannot be partially 
filled (shortened word count = 0). 



Errors: 

Code 

1 
2 



Explanation 

Attempted to write past end-of-file. 
Hardware error. 
Channel was not opened. 



Example: 

Refer to the example following .READ. 
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.WRITC 

The .WRITC request transfers a specified number of words from memory to 
a specified channel. Control returns to the user program immediately after 
the request is queued. Execution of the user program continues until the 
.WRITC is complete, then control passes to the routine specified in the 
request. When an RTS PC is encountered in the completion routine, control 
returns to the user program. 

Macro Call: .WRITC area,chan,buf,wcnt,crtn,blk 
where: 



area 
chan 
buf 
went 



is the address of a five-word EMT argument block 

is a channel number in the range to 376(octal) 

is the address of the memory buffer to be used for output 

is the number of words to be written 



blk 



crtn is the address of the completion routine to be entered 



is the block number to be written. For a file-structured 
LOOKUP or .ENTER, the block number is relative to the 
start of the file. For a non-file-structured .LOOKUP or .EN- 
TER, the block number is the absolute block number on the 
device. Your program should normally update blk before it is 
used again. See the RT~11 Software Support Manual for the 
significance of the block number for devices such as line 
printers and paper tape readers 



Request Format: 
RO 



Tiat: 


U/(tiTC 


area: 


11 chan 




blk 




buf 




went 




crtn 



NOTE 

When any .WRITE, .WRITC, or .WRITW programmed re- 
quest is returned, RO contains the number of words requested 
if the write is to a sequential-access device (for example, 
magtape). If the write is to a random-access device (disk or 
DECtape), RO contains the number of words that will be writ- 
ten (.WRITE or .WRITC) or have been written (.WRITW). If a 
request is made to write past the end-of-file on a random- 
access device, the word count is shortened and an error is 
returned. The shortened word count is returned in RO. If a 
write goes past EOF on magtape, the handler returns an er- 
ror and R0 = 0. Note that the write is done and a completion 
routine, if specified, is entered, unless the request cannot be 
partially filled (shortened word count == 0). 
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When a .WRITC completion routine is entered, the following conditions are 
true: 

1. RO contains the contents of the channel status word for the opera- 
tion. If bit of RO is set, a hardware error occurred during the 
transfer: Consequently, the data may be unreliable. 

2. Rl contains the octal channel number of the operation. This is 
useful when the same completion routine is to be used for several 
different transfers. 

3. Registers RO and Rl are available for use by the routine, but all 
other registers must be saved and restored. Data cannot be passed 
between the main program and completion routines in any regis- 
ter or on the stack. 



Errors: 

Code 

1 
2 



Explanation 

End-of-file on output. Tried to write outside limits of file. 
Hardware error occurred. 
Specified channel is not open. 



Example: 

Refer to the example following .RE ADC. 

.WRITW 

The .WRITW request transfers a specified number of words from memory to 

the specified channel. Control returns to your program when the .WRITW 

is complete. 

Macro Call: .WRITW area,chan,buf,wcnt,blk 



where: 



area is the address of a five-word EMT argument block 

chan is a channel number in the range to 376(octal) 

buf is the address of the buffer to be used for output 

went is the number of words to be written. The number must be 
positive 

blk is the block number to be written. For a file-structured 
.LOOKUP or .ENTER, the block number is relative to the 
start of the file. For a non-file-structured .LOOKUP or .EN- 
TER, the block number is the absolute block number on the 
device. Your program should normally update blk before it is 
used again. See the RT-11 Software Support Manual for the 
significance of the block number for devices such as line 
printers and paper tape readers 
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Request Format: 
RO 



area: 



11 chan 



blk 



buf 



went 







NOTE 

When any .WRITE, .WRITC, or .WRITW programmed re- 
quest is returned, RO contains the number of words requested 
if the write is to a sequential-access device (for example, 
magtape). If the write is to a random-access device (disk or 
DECtape), RO contains the number of words that will be writ- 
ten (.WRITE or .WRITC) or have been written (.WRITW). If a 
request is made to write past the end-of-file on a random- 
access device, the word count is shortened and an error is 
returned. The shortened word count is returned in RO. If a 
write goes past end-of-file on magtape, the handler returns 
an error and RO = 0. Note that the write is done and a comple- 
tion routine, if specified, is entered, unless the request cannot 
be partially filled (shortened word count = 0). 

Errors: 

Code Explanation 

Attempted to write past EOF. 

1 Hardware error. 

2 Channel was not opened. 
Example: 

Refer to the example following .READW. 
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Chapter 3 

System Subroutine Description and Examples 



This chapter presents all SYSLIB functions and subroutines in alphabetical 
order and provides a detailed description of each one. An example of each 
call in a FORTRAN program is given. 



3.1 AJFLT 



The AJFLT function converts an INTEGER*4 value to a REAL*4 value 
and returns that result as the function value. 

Form: a = AJFLT (jsrc) 

where: 

jsrc is the INTEGER*4 variable to be converted 
Function Results: 

The function result is a REAL*4 value. 
Errors: 

None. 
Example: 

The following example converts the INTEGER*4 value contained in 
JVAL to single precision (REAL*4), multiplies it by 3.5, and stores 
the result in VALUE. 

REAL*^ VALUE (AJFLT 
INTEGER*^ JMAL 



UALUE=AJFLT(JVAL)«3.5 



3.2 CHAIN 



The CHAIN subroutine allows a background program (or any program in 
the single-job system) to transfer control directly to another background 
program and pass specified information to it. CHAIN cannot be called from 
a completion or interrupt routine. The FORTRAN impure area is not pre- 
served across a chain. Therefore, when chaining from one program to an- 
other, the information must be reset in the program being chained to. 
When chaining to any other program, the user should explicitly close the 
opened logical units with calls to the CLOSE routine. Any routines speci- 
fied in a FORTRAN USEREX library call are not executed if a CHAIN is 
accomplished (see Appendix B in the RT-lllRSTSIE FORTRAN IV User's 
Guide). 
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Form: CALL CHAIN (dblk,var,wcnt) 
where: 

dblk is the address of a four-word Radix-50 descriptor of the file 
specification for the program to be run (see the PDP-11 FOR- 
TRAN Language Reference Manual for the format of the file 
specification) 

var is the first variable (which must start on a word boundary) in 
a sequence of variables with increasing memory addresses to 
be passed between programs in the chain parameter area (ab- 
solute locations 510 to 777). A single array or a COMMON 
block (or portion of a COMMON block) is a suitable sequence 
of variables 

went is a word count specifying the number of words (beginning at 
var) to be passed to the called program. The argument went 
may not exceed 60. If no words are passed, then a word count 
of must be supplied 

If the size of the chain parameter area is insufficient, it can be increased by 
specifying the /B (or /BOTTOM) option to LINK for both the program exe- 
cuting the CHAIN call and the program receiving control. 

The data passed can be accessed through a call to the RCHAIN routine. For 
more information on chaining to other programs, see the .CHAIN pro- 
grammed request (Section 2.3). 

Errors: 

None. 

Example: 

The following example transfers control from the main program to 
PROG.SAV on DTO, and passes it variables. 

DIMENSION SPEC(2) 

INTEGER*2 DATA(IO) 

DATA SPEC/BRDTOPRO t 6RG BM / 



CALL CHAIN ( SPEC »DATA * 1 ) 

3.3 CLOSEC/ICLOSE 

The CLOSEC subroutine terminates activity on the specified channel and 
frees it for use in another operation. The handler for the associated device 
must be in memory. CLOSEC cannot be called from a completion or inter- 
rupt routine. 

Form: CALL CLOSEC (chan[,i]) 
i = CLOSEC(chan) 
CALL ICLOSE (chan[,i]) 
i - ICLOSE(chan) 
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where: 

chan is the channel number to be closed. This argument must be 
located so that the USR cannot swap over it 

i is the error return if a protection violation occurs 

A CLOSEC or PURGE must eventually be issued for any channel opened 
for input or output. A CLOSEC call specifying a channel that is not open is 
ignored. 

A CLOSEC performed on a file that was opened via an lENTER causes the 
device directory to be updated to make that file permanent. If the device 
associated with the specified channel already contains a file with the same 
name and type, the old copy is deleted when the new file is made perma- 
nent. If the file name is protected, then a protection error is generated. A 
CLOSEC on a file opened via LOOKUP does not require any directory 
operations. 

When an entered file is closed, its permanent length reflects the highest 
block of the file written since the file was entered; for example, if the 
highest block written is block number 0, the file is given a length of 1; if the 
file was never written, it is given a length of 0. If this length is less than 
the size of the area allocated at lENTER time, the unused blocks are re- 
claimed as an empty area on the device. 

Errors: 

i = Normal return. 
= -4 A protected file with the same name already exists on a 
device. The CLOSEC is performed, resulting in two files on 
the device with the same name. 

Example: 

The following example creates and processes a 56-block file. 

REAL#4 DBLK(Z) 

DATA DBLK/GRBYONEW.GRFILDAT/ 

DATA IBIZE/5B/ 



ICHAN=IGETC( ) 

IFdCHAN.LT.O) GOTO 100 

I ERR = I ENTER ( I CHAN »DBLK >ISIZE) 

IF(IERR.LT.O)GOTO 20 
20 GOTO( 110 ,120 »130)ABS(IER) 

CALL ICLOSE (ICHAN,!) 

IF(I.EQ.-4) GOTO 200 

CALL IFREEC(ICHAN) 

CALL EXIT 
100 STOP 'NO AVAILABLE CHANNELS' 
110 STOP 'CHANNEL ALREADY IN USE' 
120 STOP 'NOT ENOUGH ROOM ON DEVICE' 
130 STOP 'DEVICE IN USE' 
200 STOP 'PROTECTION ERROR' 

END 
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3.4 CONCAT 



The CONCAT subroutine concatenates two character strings. 

Form: CALL CONCAT (a,b,out[,len[,err]]) 

where: 

a is the array containing the left string. The string must be ter- 
minated with a null byte 

b is the array containing the right string. The string must be 
terminated with a null byte 

out is the array into which the concatenated result is placed. This 
array must be at least one element longer than the maximum 
length of the resultant string (that is, one greater than the 
value of len, if specified) 

len is the integer number of characters representing the maximum 
length of the output string. The effect of len is to truncate the 
output string to a given length, if necessary 

err is the logical error flag set if the output string is truncated to 
the length specified by len 

CONCAT sets the string in the array out to be the string in array a imme- 
diately followed on the right by the string in array h and a terminating null 
character. 

NOTE 

Any combination of string arguments is allowed, so long as b 
and out do not specify the same array. 

Concatenation stops when a null character is detected in h, or when the 
number of characters specified by len has been moved. 

If either the left or right string is a null string, the other string is copied to 
out. If both are null strings, then out is set to a null string. The old contents 
of out are lost when this routine is called. 



Errors: 



Error conditions are indicated by err, if specified. If err is given and 
the output string would have been longer than len characters, then 
err is set to .TRUE.; otherwise, err is unchanged. 



Example: 



The following example concatenates the string in array STR and the 
string in array IN and stores the resultant string in array OUT. OUT 
cannot be larger than 29 characters. 



LOGICAL*! IN(22) tOUTOO) ,STR(7) 



CALL CONCATfSTR fIN (OUT .29) 
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3.5 CVTTIM 



The CVTTIM subroutine converts a two-word internal format time to 
hours, minutes, seconds, and ticks. 

Form: CALL CVTTIM (time,hrs,min,sec,tick) 

where: 

time is the two-word internal format time to be converted. If time 
is considered as a two-element INTEGER*2 array, then: 

time (1) is the high-order time 
time (2) is the low-order time 

hrs is the integer number of hours 

min is the integer number of minutes 

sec is the integer number of seconds 

tick is the integer number of ticks (1/60 of a second for 60-cycle 
clocks; 1/50 of a second for 50-cycle clocks) 

Errors: 

None. 

Example: 

INTEGER*^ ITIME 



CALL GTIM(ITIME) ! GET CURRENT TIME-OF-DAY 

CALL CUTTIM( ITIME » IHRS . I M IN . ISEC » ITCK ) 

IF( IHRS.GE. IZ.AND. IHRS.LT.13) GOTO 100 ITIME FOR LUNCH 



3.6 DEVICE (FB and XM Only) 



The DEVICE subroutine allows you to set up a list of addresses to be loaded 
with specified values when the program is terminated. If a job terminates 
or is aborted with a CTRL/C from the terminal, this list is picked up by the 
system and the appropriate addresses are set up with the corresponding 
values. 

This function is primarily designed to allow user programs to load device 
registers with necessary values. In particular, it is used to turn off a de- 
vice's interrupt enable bit when the program servicing the device termi- 
nates. 

Only one address list can be active at any given time; hence, if multiple 
DEVICE calls are issued, only the last one has any effect. The list must not 
be modified by the program after the DEVICE call has been issued, and the 
list must not be located in an overlay or an area over which the USR swaps. 

The second argument of the call {link) provides support for a linked list of 
tables. The link argument is optional and causes the first word of the list to 
be processed as the link word. 
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Form: CALL DEVICE (ilist[,link]) 
where: 

ilist is an integer array that contains two-word elements, each 
composed of a one-word address and a one-word value to be 
put at that address, terminated by a zero word. On program 
termination, each value is moved to the corresponding address 

link is an optional argument that can be any value. This indicates 
that a linked list table is to be used 

If the linked list form is used the first word of the array is the 
link list pointer 

For more information on loading values into device registers, see the .DE- 
VICE programmed request (Section 2.16). 

Errors: 

None. 

Example: 

INTEGER*2 IDRllO) IDEUICE ARRAY SPEC 

DATA IDRll (1 )/"lB7770/ !DR11 CSR ADDRESS (OCTAL) 

DATA IDRll(2)/0/ ! VALUE TO CLEAR INTERRUPT ENABLE 

DATA IDRll(3)/0/ ! AND END-OF-LIST FLAG 

CALL DEMICE(IDRll) ! SET UP FOR ABORT 



3.7 DJFLT 

The DJFLT function converts an INTEGER*4 value into a REAL*8 (DOU- 
BLE PRECISION) value and returns that result as the function value. 

Form: d = DJFLT (jsrc) 

where: 

jsrc specifies the INTEGER*4 variable to be converted 

Notes: 

If DJFLT is used, it must be defined in the FORTRAN program, either 
explicitly (REAL*8 DJFLT) or implicitly (IMPLICIT REAL*8 (D)). Without 
a definition, DJFLT is assumed to be REAL*4 (single precision). 

Function Results: 

The function result is the REAL*8 value that is the result of the operation. 

Errors: 

None. 

Example: 

INTEGER*^ JMAL 
REAL*8 DJFLT. D 

* 

D=DJFLT( JMAL) 
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3.8 GETSTR 



The GETSTR subroutine reads a formatted ASCII record from a specified 
FORTRAN logical unit into a specified array. The data is truncated (trail- 
ing blanks removed) and a null byte is inserted at the end to form a charac- 
ter string. 

GETSTR can be used in main program routines or in completion routines, 
but it cannot be used in both at the same time. If GETSTR is used in a 
completion routine, it cannot be the first I/O operation on the specified 
logical unit. 

Form: CALL GETSTR (lun,out,len,err) 

where: 

lun is the integer FORTRAN logical unit number of a formatted 
sequential file from which the string is to be read 

out is the array to receive the string; this array must be at least 
one element longer than len 

len is the integer number representing the maximum length of the 
string that is allowed to be input 

err is the LOGICAL*! error flag that is set to .TRUE, if an error 
occurred. If an error did not occur, the flag is .FALSE 



Errors: 



Error conditions are indicated by err. If err is .TRUE., the values 
returned are as follows: 

err = -1 End-of-file for a read operation, 
err = -2 Hard error for a read operation, 
err = -3 More than len bytes were contained in a record. 



Example: 



The following example reads a string of up to 80 characters from 
logical unit 5 into the array STRING. 



L0GICAL#1 STRING(B1 ) tERR 



CALL GETSTR(5 tSTRING »80 tERR) 



3.9 GTIM 



The GTIM subroutine returns the current time of day. The time is returned 
in two words and is given in terms of clock ticks past midnight. If the 
system does not have a line clock, a value of is returned. If an RT-11 
monitor TIME command has not been entered, the value returned is the 
time elapsed since the system was bootstrapped, rather than the time of 
day. 
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Form: CALL GTIM (itime) 

where: 

itime is the two-word area to receive the time of day 

The high-order time is returned in the first word, the low-order time in the 
second word. The CVTTIM routine (see Section 3.5) can be used to convert 
the time into hours, minutes, seconds, and ticks. CVTTIM performs the 
conversion based on the monitor configuration word for 50- or 60-cycle 
clocks. Under an FB or XM monitor, the time-of-day is automatically reset 
after 24:00 when a GTIM is executed; under the single-job monitor, it is 
not. 

Errors 

None. 

Example: 

INTEGER*^ JTIME 

t 

CALL GTIM(JTIME) 

3.10 GTJB/IGTJB 

The GTJB subroutine returns information about a job in the system. 

Form: CALL GTJB (addr,|jobblk [,i]]) 
i = GTJB (addr,|jobblk]) 
CALL IGTJB (addr,[jobblk [,i]]) 
i = IGTJB (addr,|jobblk]) 



where: 



addr is the address of an eight- or twelve-word block into which 
the parameters are passed 

The parameters returned are as follows: 

Word 1 Job Number = priority level*2 (background 
job is 0, system jobs are 2, 4, 6, 10, 12, 14, 
foregiound job is 16 in system job monitors; 
background job is 0, foreground job is 2 in FB 
and XM monitors; job number is in SJ moni- 
tor) 

2 High-memory limit of job partition (last loca- 
tion plus 2) 

3 Low-memory limit of job partition (first loca- 
tion) 

4 Pointer to I/O channel space 

5 Address of job's impure area in FB and XM 
monitors (0 in SJ) 
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6 Low byte: unit number of job's console termi- 
nal (only if the multiterminal option is pres- 
ent; when the multiterminal feature is not 
used) 

7 Virtual high limit for a job created with the 
linker /V option (XM only; in SJ and FB and 
where the Linker /V option is not used) 

8—9 Reserved for future use 
10-12 ASCII logical job name (system job monitors 
only) 

jobblk is a pointer to a three-word ASCII job name for which data 
is being requested. Do not specify this argument when re- 
questing the eight-word block 

i is an error return if the job is not running 

If one argument is used with the call, only the first eight parameters will be 
passed. For example, 

INTEGER IJPARM(8) 
CALL GTJB (IJPARM) 
I - GTJB (IJPARM) 

At least a comma must follow the argument to pass the information into a 
12-word block. For example, 

INTEGER IJPARM(12) 
CALL GTJB (IJPARM,) 
I = GTJB (IJPARM,) 



Errors: 



i = Normal return. 
= -1 No such job currently running. 



Example: 



C THIS IS AN EXAMPLE UNDER A SYSTEM 
C JOB MONITOR TO SEE IF THE FOREGROUND 
C JOB IS RUNNING 
DIMENSION JDATAdZ) 



I = GTJB (JDATA. IS) 

IF (I.EO.O) GOTO 20 

TYPE 10 
10 FORMAT( 'NO FG JOB! ' ) 

STOP 
20 



3.11 GTLIN 



The GTLIN subroutine transfers a line of input from the console terminal 
or an active indirect command file to the user program. This request allows 
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you to input information at the console terminal, and it allows the program 
to operate through indirect files. This subroutine requires the USR. The 
maximum size of the input line is 80 characters. See the .GTLIN pro- 
grammed request for setting bits in the Job Status Word to pass lowercase 
letters and to establish a nonterminating condition. 

Form: CALL GTLIN (result[,prompt]) 

where: 

result is the array receiving the string. This LOGICAL*! array 
contains a maximum of 80 characters plus as the end 
indicator, and therefore must be dimensioned to at least 81 
elements 

prompt is a LOGICAL*! array containing an optional prompt 
string to be printed before the input line is received. The 
string format is the same as that used by the PRINT sub- 
routine. If this argument is not present, no prompt is 
printed 

Errors: 

None. 

Example: 

L0GICAL#1 INP(SO) ,PROMT(B) 

DATA PROMT / 'N ' , ' A ' » ' M ' t ' E ' t '? ' . "200/ 



CALL GTLINCINP, PROMT) 

« 
« 

3.12 lABTIO 

The lABTIO function aborts I/O on a specified channel. 

Form: CALL lABTIO (chan) 

where: 

chan is the channel number for which to abort I/O 
Errors: 

None. 

3.13 lADDR 

The lADDR function returns the ! 6-bit absolute memory address of its 
argument as the integer function value. 

Form: i = lADDR (arg) 
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where: 



arg is the variable or constant whose memory address is to be ob- 
tained. The value obtained by passing an expression as arg is 
unpredictable 



Errors: 

None. 
Example: 



lADDR can be used to find the address of an assembly language 
global area. For example: 



EXTERNAL CAREA 
J=IADDR(CAREA) 



3.14 lAJFLT 



The lAJFLT function converts an INTEGER*4 value to a REAL*4 value 
and stores the result. 

Form: i = lAJFLT (jsrc,ares) 

where: 

jsrc is the INTEGER*4 variable to be converted 

ares is the REAL*4 variable or array element to receive the con- 
verted value 

Function Results: 

i = -1 Normal return; the result is negative. 
= Normal return; the result is 0. 
= 1 Normal return; the result is positive. 

Errors: 

i = -2 Significant digits were lost during the conversion. 

Example: 

INTEGER*^ JMAL 
REAL»4 RESULT 



IF(IAJFLT(JUAL>RESULT) .EQ.-2) TYPE 99 
99 FORMAT (' OVERFLOW IN INTEGER*/^ TO REAL CONUERSION') 



3.15 lASIGN 



The lASIGN function sets information in the FORTRAN logical unit table 
(overriding the defaults) for use when the FORTRAN Object Time System 
(OTS) opens the logical unit. This function can be used with ICSI (see 
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Section 3.20) to allow a FORTRAN program to accept a standard CSI input 
specification. lASIGN must be called before the unit is opened; that is, 
before any READ, WRITE, PRINT, TYPE, ACCEPT, or OPEN statements 
are executed that reference the logical unit. 

Form: i = lASIGN (lun,idev[,ifiltyp[,isize[,itype]]]) 

where: 



lun 



idev 



ifiltyp 



isize 



itype 



is an INTEGER*2 variable, constant, or expression specify- 
ing the FORTRAN logical unit for which information is 
being specified 

is a one- word Radix-50 device name; this can be the first 
word of an ICSI input or output file specification 

is a three-word Radix-50 file name and file type; this can be 
words 2 through 4 of an ICSI input or output file specifica- 
tion 

is the length (in blocks) to allocate for an output file; this 
can be the fifth word of an ICSI output specification. If 0, the 
larger of either one-half the largest empty segment or the 
entire second largest empty segment is allocated. If the 
value specified for length is -1, the entire largest empty 
segment is allocated 

is an integer value determining the optional attributes to be 
assigned to the file. This value is obtained by adding the 
values that correspond to the desired operations: 

1 Use double buffering for output. 

2 Open the file as a temporary file. 

4 Force a LOOKUP on an existing file during the first 
I/O operation. (Otherwise, the first FORTRAN I/O oper- 
ation determines how the file is opened. Normally if the 
first I/O operation is a write, an lENTER would be per- 
formed on the specified logical unit. A read always 
causes a LOOKUP.) 
8 Do not expand carriage control information. 
16 Expand carriage control information (see Notes below). 
32 File is read only. 



Notes: 



Expanded carriage control information applies only to formatted output 
files and means that the first character of each record is used as a carriage 
control character when processing a write operation to the given logical 
unit. The first character is removed from the record and converted to the 
appropriate ASCII characters to simulate the requested carriage control. 

If carriage control information is not expanded, the first character of each 
record is unmodified and the FORTRAN OTS outputs a line feed, followed 
by the record, followed by a carriage return. 

If carriage control is unspecified, the FORTRAN OTS sends expanded car- 
riage control information to the terminal and line printer and sends unex- 
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panded carriage control information to all other devices and files. See the 
PDP-11 FORTRAN Language Reference Manual for further carriage con- 
trol information. 



Errors: 



i = Normal return. 

<> The specified logical unit is already in use, or there is no 
space for another logical unit association. 



Example: 



The following example (1) creates an output file on logical unit 3, 
using the first output file given to the RT-11 Command String Inter- 
preter (CSI), (2) sets up the output file for double buffering, (3) cre- 
ates an input file on logical unit 4, based on the first input file specifi- 
cation given to the RT-11 CSI, and (4) makes the input file available 
for read-only access. 



INTEGER*2 SPECOB) 

REAL*4 EXT (2) 

DATA EXT/6RDATDAT»BRDATDAT/ 



IDEFAULT FILE TYPE IS DAT 



3.16 ICDFN 



10 IFdCSKSPEC .EXT . . >0) .NE.O) GOTO 10 

C 

C DO NOT ACCEPT ANY SWITCHES 

C 

CALL IASIGN(3>SPEC(1) fSPEC(2) .SPEC(5) .1) 
CALL IASIGN(a .SPEC( IB) .SPECtl?) ,0*32) 



The ICDFN function increases the number of input/output channels. Note 
that ICDFN defines new channels; any channels defined with an earlier 
ICDFN function are not used. Thus, an ICDFN for 20(decimal) channels 
(while the 16[decimal] original channels are defined) causes only 20 I/O 
channels to exist; the space for the original 16 is unused. The space for the 
new channel area is allocated out of the free space managed by the FOR- 
TRAN system. 

Form: i = ICDFN (num[,area]) 

where: 

num is the integer number of channels to be allocated. The number 
of channels must be greater than 16 and can be a maximum of 
256. The program can use all new channels greater than 16 
without a call to IGETC; the FORTRAN system input/output 
uses only the first 16 channels. This argument must be posi- 
tioned so that the USR cannot swap over it 

area is the space allocated from within the calling program. Under 
FB and SJ monitors; be sure that the space is outside the USR 
swapping area. If this argument is not specified, the space for 
the channels is allocated in the FORTRAN OTS work area 
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Notes: 

1. ICDFN cannot be issued from a completion or interrupt routine. 

2. It is recommended that the ICDFN function be used at the beginning of 
the main program before any I/O operations are initiated. 

3. If ICDFN is executed more than once, a completely new set of channels 
is created each time ICDFN is called. 

4. ICDFN requires that extra memory space be allocated to foreground 
programs (see Section 1.2.4.1). 

5. Any channels that were open prior to the ICDFN are copied over to the 
new set of channel status tables. 

Function Results: 

i = Normal return. 
= 1 An attempt was made to allocate fewer channels than al- 
ready exist. 
= 2 Not enough free space is available for the channel area. 

Example: 

IF(ICDFN(2^) .E0.2) STOP 'NOT ENOUGH MEMORY' 

3.17 ICHCPY (FB and XM Only) 

The ICHCPY function opens a channel for input, logically connecting it to a 
file that is currently open by another job for either input or output. This 
function can be used by either the foreground or the background job. An 
ICHCPY must be done before the first read or write for the given channel. 

Form: i = ICHCPY (chan,ochan[,jobblk]) 
where: 

chan is the channel the job will use to read the data. You must 
obtain this channel through an IGETC call, or you can use 
channel 16 or higher if you have done an ICDFN call 

ochan is the channel number of the other job that is to be copied 

jobblk is a pointer to a three-word ASCII job name 

Notes: 

1. If the other job's channel was opened with an lENTER function or a 
.ENTER programmed request to create a file, your channel indicates a 
file that extends to the highest block that the creator of the file had 
written at the time the ICHCPY was executed. 

2. A channel that is open on a sequential-access device should not be 
copied, because buffer requests can become intermixed. 
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Your program can write on a copied channel to a file that is being 
created by the other job, just as your program could if it were the crea- 
tor. When your channel is closed, however, no directory update takes 
place. 



Errors: 



i = Normal return. 
= 1 Specified job does not exist or does not have the specified 

channel (ochan) open. 
= 2 Channel (chan) is already open. 

3.18 ICLOSE 

See the SYSLIB subroutine CLOSEC. 

3.19 ICMKT 

The ICMKT function cancels one or more scheduling requests (made by an 
ISCHED, ITIMER, or MRKT routine). Support for ICMKT in SJ requires 
that timer support be created through SYSGEN. 

Form: i = ICMKT (id,time) 

where: 

id is the identification integer of the request to be canceled. If id 

is equal to 0, all scheduling requests are canceled 

time is the name of a two-word area in which the monitor returns 
the amount of time remaining in the canceled request 

For further information on canceling scheduling requests, see the .CMKT 
programmed request (Section 2.5). 

Errors: 

i = Normal return. 
= 1 id was not equal to and no scheduling request with that 
identification could be found. 

Example: 

INTEGER*^ J 

« 
4 

« 

CALL ICMKT(0»J> ! ABORT ALL TIMER REQUESTS NOW 

t 
f 
* 

END 
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3.20 ICSI 



The ICSI function calls the RT-11 Command String Interpreter in special 
mode to parse a command string and return file descriptors and options to 
the program. In this mode, the CSI does not perform any handler 
IFETCHes, CLOSECs, lENTERs, or LOOKUPs. ICSI cannot be called from 
a completion or interrupt routine. This subroutine requires the USR. 

Form: i = ICSI (filspc,deftyp,[cstring],[option],n) 

where: 

filspc is the 3 9- word area to receive the file specifications. The 
format of this area (considered as a 39-element INTE- 
GER*2 array) is: 

Word 1 output file number 1 

4 specification 

5 output file number 1 length 

6 output file number 2 
9 specification 

10 output file number 2 length 

11 output file number 3 

14 specification 

15 output file number 3 length 

16 input file number 1 

19 specification 

20 input file number 2 

23 specification 

24 input file number 3 

27 specification 

28 input file number 4 

31 specification 

32 input file number 5 

35 specification 

36 input file number 6 
39 specification 

deftyp is the table of Radix-50 default file types to be assumed 
when a file is specified without a file type: 

deftyp(l) is the default for all input file types 

deftjT)(2) is the default file type for output file number 1 

deftyp(3) is the default file type for output file number 2 

deft5T)(4) is the default file type for output file number 3 

cstring is the area that contains the ASCIZ command string to be 
interpreted; the string must end in a zero byte. If the argu- 
ment is omitted, the system prints the prompt character (*) 
at the terminal and accepts a command string. If input is 
from an indirect command file, the next line of that file is 
used 
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option is the name of an INTEGER*2 array dimensioned (4,n) 
where n represents the number of options defined to the 
program. This argument must be present if the value speci- 
fied for n is non-zero. This array has the following format 
for the jth option described by the array: 

option(l,j) is the one-character ASCII name of the option 
option(2,j) is set by the routine to 0, if the option did not 

occur; to 1, if the option occurred without a 

value; to 2, if the option occurred with a value 
option(3,j) is set to the file number on which the option is 

specified 
option(4,j) is set to the specified value if option(2,n) is 

equal to 2 

n is the number of options defined in the array option 

Notes: 

1. The array option must be set up to contain the names of the valid 
options. For example, use the following to set up names for five options: 

INTEGER*2 SW(a»5) 

DATA SW(ltl)/'S'/»SW(l>Z)/'M'/tSW(l»3)/'I'/ 

DATA SWd .-^D/'L'/ .SWd »5)/'E'/ 

2. Multiple occurrences of the same option are supported by allocating an 
entry in the option array for each occurrence of the option. Each time 
the option occurs in the option array, the next unused entry for the 
named option is used. 

3. The arguments of ICSI must be positioned so that the USR cannot swap 
over them. For more information on calling the Command String Inter- 
preter, see the .CSISPC programmed request (Section 2.11). 

Errors: 

i = Normal return. 
= 1 Illegal command line; no data was returned. 
= 2 An illegal device specification occurred in the string. 
= 3 An illegal option was specified, or a given option was spec- 
ified more times than were allowed for in the option array. 

Example: 

The following example causes the program to loop until a valid com- 
mand is typed at the console terminal. 

INTEGER#2 SPEC(39) 

REAL*a EXT(Z> 

DATA EXT/BRDATDAT *BRDATDAT/ 



10 TYPE 99 

99 FORMAT (' ENTER MALID CSI STRING WITH NO OPTIONS') 
IFdCSKSPEC »EXT » t »0) .NE.O) GOTO 10 
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3.21 ICSTAT 

The ICSTAT function obtains information about a channel. 

Form: i = ICSTAT (chan,addr) 

where: 

is the channel whose status is desired 



chan 
addr 



Errors: 



is a six-word area to receive the status information. The area, 
as a six-element INTEGER*2 array, has the following format: 

Word 1 channel status word 

2 starting absolute block number of file on this chan- 
nel 

3 length of file 

4 highest block number written since file was opened 

5 unit number of device with which this channel is 
associated 

6 Radix-50 of device name with which the channel is 
associated 



i = Normal return. 
= 1 Channel specified is not open. 



Example: 



The following example obtains channel status information about 
channel I. 

INTEGER*Z AREA(B) 
1=7 

IFdCSTATd tAREA) .NE.O) TYPE 99>I 
99 FORMATdX t 'CHANNEL' fI4 I'lS NOT OPEN') 



3.22 IDELET 



The IDELET function deletes a named file from an indicated device. 
IDELET requires the USR and cannot be issued from a completion or inter- 
rupt routine. 

Form: i = IDELET (chan,dblk[,seqnum]) 

where: 

chan is the channel to be used for the delete operation. You 

must obtain this channel through an IGETC call, or you 
can use channel 16(decimal) or higher if you have done an 
ICDFN call 

dblk is the four-word Radix-50 specification (dev:filnam.typ) 

for the file to be deleted 
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seqnum is the file number for cassette operations: if this argument 
is blank, a value of is assumed 

For magtape operation, it describes a file sequence number that 
can have the following values: 

Value Meaning 

-1 This value suppresses rewinding and searching for a file 
name from the current tape position. Note that if the 
position is unknown, the handler executes a positioning 
algorithm that involves backspacing until an end-of-file 
label is found. The user should not use any other value 
since all other negative values are reserved for future 
use. 

This value rewinds the magtape and spaces forward un- 
til the file name is found. 

n Where n is any positive number. This value positions 
the magtape at file sequence number n. If the file repre- 
sented by the file sequence number is greater than two 
files away from the beginning of the tape, a rewind is 
performed. If not, the tape is backspaced to the file. 

NOTE 

The arguments of IDELET must be located so that the USR 
cannot swap over them. 

The specified channel is left inactive when the IDELET is complete. IDE- 
LET requires that the handler to be used be resident (via an IFETCH call 
or a LOAD command from KMON) at the time the IDELET is issued. If the 
handler is not resident, a monitor error occurs. 

For further information on deleting files, see the .DELETE programmed 
request (Section 2.15). 

Errors: 

i = Normal return. 

= 1 Channel specified is already open. 

= 2 File specified was not found. 

= 3 Device in use. 

= 4 The file is protected and cannot be deleted. 

Example: 

The following example deletes a file named FTN5.DAT from SYO. 

REAL#4 FILNAM(Z) 

DATA FILNAM/6RSY0FTNtBR5 DAT/ 



I=IGETC( ) 

IF(I.LT.O) STOP 'NO CHANNEL 
CALL IDELETd ,FILNAM) 
CALL IFREEC(I) 
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3.23 IDJFLT 



The IDJFLT function converts an INTEGER*4 value into a REAL*8 (DOU- 
BLE PRECISION) value and stores the result. 

Form: i = IDJFLT (jsrc,dres) 

where: 

jsrc specifies the INTEGER*4 variable that is to be converted 

dres specifies the REAL*8 (or DOUBLE PRECISION) variable to 
receive the converted value 

Function Results: 



i = -1 
= 
= 1 

Errors: 

None. 

Example: 



Normal return; the result is negative. 
Normal return; the result is 0. 
Normal return; the result is positive. 



INTEGER*^ JJ 
REAL*8 DJ 



IF( IDJFLK JJ>DJ) .LE.O) TYPE 99 
99 FORMAT (' VALUE IS NOT POSITIME') 



3.24 IDSTAT 



The IDSTAT function obtains information about a particular device. It re- 
quires the USR and cannot be issued from a completion or interrupt rou- 
tine. 

Form: i = IDSTAT (devnam,cblk) 
where: 

is the Radix-50 device name 



devnam 
cblk 



is the four-word area used to store the status information. 
The area, as a four-element INTEGER*2 array, has the 
following format: 



Word 1 
2 
3 



device status word (see Section 2.25) 
size of handler in bytes 

entry point of handler (non-zero implies that 
the handler is in memory) 
size of the device (in 256-word blocks) for 
block-replaceable devices; zero for sequential- 
access devices 
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NOTE 

The arguments of IDSTAT must be positioned so that the 
USR cannot swap over them. 

IDSTAT looks for the device specified by devnam and, if found, returns four 
words of status in cblk. 



Errors: 



i - Normal return. 
= 1 Device not found in monitor tables. 



Example: 



The following example determines whether the line printer handler 
is in memory. If it is not, the program stops and prints a message to 
indicate that the handler must be loaded. 



INTEGER IDNAM 

INTEGER*2 CBLK(4) 

DATA IDNAM/3RLP / 

DATA CBLK/4#0/ 

CALL IDSTATdDNAM tCBLK) 

IF(CBLK(3) ,E0.0) STOP 'LOAD 



THE LP HANDLER AND RERUN' 



3.25 lENTER 



The lENTER function allocates space on the specified device and creates a 
tentative directory entry for the named file. If a file of the same name 
already exists on the specified device, it is not deleted until the tentative 
entry is made permanent by CLOSEC or ICLOSE. The file is attached to 
the channel number specified. This routine requires the USR. 

Form: i = lENTER (chan,dblk,length[,seqnum]) 



where: 



chan 



dblk 



length 



seqnum 



is the integer specification for the RT-11 channel to be 
associated with the file. You must obtain this channel 
through an IGETC call, or you can use channel 16 or 
higher if you have done an ICDFN call 

is the four- word Radix-50 descriptor of the file to be oper- 
ated upon 

is the integer number of blocks to be allocated for the file. 
If 0, the larger of either one-half the largest empty seg- 
ment or the entire second largest empty segment is allo- 
cated. If the value specified for length is -1, the entire 
largest empty segment is allocated (see the .ENTER pro- 
grammed request. Section 2.28) 

is a file number for cassette. If this argument is blank, a 
value of is assumed. 



System Subroutine Description and Examples 3-21 



For magtape, it describes a file sequence number that can 
have the following values: 

-2 Rewind the magtape and space forward until the file 
name is found, or until logical-end-of-tape is de- 
tected. The magtape is now positioned correctly. A 
new logical-end-of-tape is implied. 

-1 Space to the logical-end-of-tape and enter file. 

Rewind the magtape and space forward until the file 
name is found or the logical-end-of-tape is detected. 
If the file name is found, an error is generated. If the 
file name is not found, then enter file. 

n Position magtape at file sequence number re if n is 
greater than zero and the file name is not null. 

Notes: 

1. lENTER cannot be issued from a completion or interrupt routine. 

2. lENTER requires that the appropriate device handler be in memory. 

3. The arguments of lENTER must be positioned so that the USR does not 
swap over them. 

For further information on creating tentative directory entries, see the 
.ENTER programmed request (Section 2.28). 

Errors: 

i = n Normalreturn;number of blocks actually allocated (re = 

for non-file-structured TENTER). 
= -1 Channel (chan) is already in use. 
^ -2 In a fixed-length request, no space greater than or equal 

to length was found. 
= -3 Device in use. 

= -4 A file by that name already exists and is protected. 
- -5 File sequence number not found. 

Example: 

The following example allocates a channel for file TEMP.TMP on 
SYO. If no channel is available, the program prints a message and 
halts. 

REAL*/3 DBLK(2) 

DATA DBLK/GRSYOTEM fGRP TMP/ 

ICHAN=IGETC( > 

IF( ICHAN.LT.O) STOP 'NO AVAILABLE CHANNEL' 
C 

C CREATE TEMPORARY WORK FILE 

C 

IF(IENTER(ICHAN»DBLK »20) .LT.O) STOP 'ENTER FAILURE' 



CALL PURGEdCHAN) 
CALL IFREEC(ICHAN) 
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3.26 IFETCH 

The IFETCH function loads a device handler into memory from the system 
device, making the device available for input/output operations. The han- 
dler is loaded into the free area managed by the FORTRAN system. Once 
the handler is loaded, it cannot be released and the memory in which it 
resides cannot be reclaimed. IFETCH requires the USR and cannot be is- 
sued from a completion or interrupt routine. IFETCH issued from a fore- 
ground job will fail unless the handler is already in memory. 

Form: i = IFETCH (devnam) 

where: 

devnam is the one- word Radix-50 name of the device for which the 
handler is desired. This argument can be the first word of 
an ICSI input or output file specification. This argument 
must be positioned so that the USR cannot swap over it 

For further information on loading device handlers into memory, see the 
.FETCH programmed request (Section 2.30). 

Errors: 

i = Normal return. 
= 1 Device name specified does not exist. 
= 2 Not enough room exists to load the handler. 
= 3 No handler for the specified device exists on the system 
device. 

Example: 

The following example requests that the DX handler be loaded into 
memory; execution stops if the handler cannot be loaded. 

REAL*4 IDNAM 
DATA IDNAM/3RDX/ 



IF (IFETCH( IDNAM) .NE.O) STOP 'FATAL ERROR FETCHING HANDLER' 

3.27 IFPROT 

The IFPROT function sets or removes file protection for a file. 

Form: i = IFPROT (chan,filspc,prot) 

where: 

chan is the channel number to be used for the protect operation. 
You must obtain this channel through an IGETC call, or you 
can use the channel 16(decimal) or higher if you have done 
an ICDFN call 

filspc is the file specification of the file to be protected or unpro- 
tected, in the format dev:filnam.typ 

prot 1 - protect the file 

= remove protection from the file 
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Errors: 

i = Normal return. 

= 1 Channel is in use. 

= 2 File not found. 

= 3 Invalid operation. 

= 4 Invalid prot value. 

Example: 

This example protects the file SY:RT11FB.SYS against deletion. 

ICHAN = IGETCO ! ALLOCATE CHANNEL 

IF (ICHAN. LT.O) STOP 'CANNOT ALLOCATE CHANNEL' 
I = IFPROT( ICHAN, 'SY : RT 1 1 FB . SYS ' ,1 > 



END 



3.28 IFREEC 



The IFREEC function returns a specified RT-11 channel to the available 
pool of channels. Before IFREEC is called, the specified channel must be 
closed or deactivated with a CLOSEC or ICLOSE (see Section 3.3) or a 
PURGE (see Section 3.92) call. IFREEC cannot be called from a completion 
or interrupt routine. IFREEC calls must be issued only for channels that 
have been successfully allocated by IGETC calls; otherwise, the results are 
unpredictable. 

Form: i = IFREEC (chan) 

where: 

chan is the integer number of the channel to be freed 
Errors: 

i = Normal return. 
= 1 Specified channel is not currently allocated. 

Example: 

See the example under IGETC. 



3.29 IGETC 



The IGETC function allocates an RT-11 channel, in the range to 15(deci- 
mal), to be used by other SYSLIB routines and marks it in use so that the 
FORTRAN I/O system will not access it. IGETC cannot be issued from a 
completion or interrupt routine. 

Form: i = IGETCO 

Function Result: 

i = n Channel n has been allocated. 
Error: 

i = -1 No channels are available. 
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Example: 



ICHAN=IGETC( ) ! ALLOCATE CHANNEL 

IF(ICHAN.LT.O) STOP 'CANNOT ALLOCATE CHANNEL' 



CALL IFREEC(ICHAN) 



IFREE IT WHEN THROUGH 



END 



3.30 IGETSP 



The IGETSP subroutine obtains free space from the FORTRAN system and 
returns the address and size (in number of words) of the allocated space. 
When this space is obtained, it is allocated for the duration of the program. 

Form: i = IGETSP (min,max,iaddr) 

where: 

min is the minimum space to be obtained without an error indi- 
cating that the desired amount of space is not available 

max is the maximum space to be obtained 

iaddr is the integer specifying the address of the start of the free 
space (buffer). Note that iaddr does not directly denote the 
storage area as a standard FORTRAN variable would. 
Rather, it denotes a word that contains the address of the 
storage space. It is most useful with IPEEK and IPOKE, or 
with assembly language subroutines 

NOTE 

Extreme caution should be exercised to avoid using all of the 
free space allocated by the FORTRAN system. If the FOR- 
TRAN system runs out of dynamic free space, fatal errors 
(Error 29, 30, 42, and so forth) occur. See the RT-11 System 
Message Manual. 

Function Results: 

i = n The actual size allocated whose value is min .LE. n .LE. 
mux. The size (min, max, n) is specified in words. 



Error: 



i = -1 Not enough free space is available to meet the minimum 
requirements; no allocation was taken from the FORTRAN 
system free space. 



Example: 



N= IGETSP (25B »25S » I BUFF) 

IF(N.LT.O) STOP 'CANNOT GET BUFFER SPACE!' 



!GET 25G WORD BUFFER 
! NO SPACE AVAILABLE 
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3.31 IGTJB 

See the SYSLIB subroutine GTJB, Section 3.10. 

3.32 IJCVT 

The IJCVT function converts an INTEGER*4 value to INTEGER*2 format. 
If ires is not specified, the result returned is the INTEGER*2 value ofjsrc. 
If ires is specified, the result is stored there. 

Form: i = IJCVT (jsrc[,ires]) 

where: 

jsrc specifies the INTEGER*4 variable or array element whose 
value is to be converted 

ires specifies the INTEGER*2 entity to receive the conversion re- 
sult 

Function Results (if ires is specified): 

i = -2 An overflow occurred during conversion. 

= -1 Normal return; the result is negative. 

= Normal return; the result is 0. 

= 1 Normal return; the result is positive. 

Errors: 

None. 

Example: 

INTEGER#a jyAL 
INTEGER*2 lUAL 



IF( IJCMT( JMAL tlUAL) .EO.-Z) TYPE 99 
99 FDRMAK' NUMBER TOO LARGE IN IJCMT CONUERSION') 

3.33 ILUN 

The ILUN function returns the RT-11 channel number with which a FOR- 
TRAN logical unit is associated. 

Form: i = ILUN (lun) 

where: 

lun is an integer expression whose value is a FORTRAN logical 
unit number in the range 1-99 

Function Results: 

= +n RT-11 channel number ra is associated with Zwre. 

Errors: 

i = -1 Logical unit is not open. 
= -2 Logical unit is opened to console terminal. 
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Example: 

PRINT 99 
99 FORMAT(' PRINT DEFAULTS TO LOGICAL UNIT G* WHICH FURTHER DEFAULTS TO LPs') 
ICHAN=ILUN(B) IWHICH RT-U CHANNEL IS RECEigiNG I/O? 

3.34 INDEX 

The INDEX subroutine searches a source string for the occurrence of a 
pattern string and returns the character position of the first occurrence of 
the pattern within the source. 

Form: CALL INDEX (a,pattrn,[i],m) 

or 

m = INDEX (a,pattrn[,i]) 

where: 

a is the array containing the source string to be searched; it 

must be terminated by a null byte 

pattrn is the string being sought; it must be terminated by a null 
byte 

i is the integer starting character position of the search in a. 

If i is omitted, a is searched beginning at the first character 
position 

m is an integer variable to store the result of the search; m is 

set to the starting character position of pattrn in a, if found; 
otherwise m is 

Errors: 

None. 

Example: 

The following example searches the array STRING for the first occur- 
rence of strings EFG and XYZ and searches the string ABCABCABC 
for the occurrence of string ABC after position 5. 

CALL SCOPY( 'ABCDEFGHI ' (STRING) UNITIALIZE STRING 

CALL INDEK(STRING t'EFG' . »M) !M = 5 

CALL INDEX(STRING.'XYZ' t .N) !N = 

CALL INDEX( 'ABCABCABC t'ABC t5,L> !L = 7 

3.35 INSERT 

The INSERT subroutine replaces a portion of one string with another 
string. 

Form: CALL INSERT (in,out,i[,m]) 
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where: 

in is the array containing the string being inserted. The string 
must be terminated with a null if the number of characters is 
less than the value of m (below), or if m is not specified 

out is the array containing the string being modified. The string 
must be terminated with a null 

i is the integer specifying the character position in out at which 

the insertion begins 

m is the integer maximum number of characters to be inserted 

If the maximum number of characters (m) is not specified, all characters to 
the right of the specified character position {i) in the string being modified 
are replaced by the string being inserted. The insert string (in) and the 
string being modified {out) can be in the same array only if the maximum 
number of characters (m) is specified and is less than or equal to the differ- 
ence between the position of the insert (i) and the maximum string length 
of the array. 

Errors: 

None. 

Example: 



CALL SCOPYt 'ABCDEFGHIJ' ,S1) 
CALL SC0PY(S1 (S2) 
CALL INSERK '123' ,S1 ,6.3) 
CALL INSERK '123' .32,^) 



! INITIALIZE STRING 1 
! INITIALIZE STRING 2 
!S1 = 'ABCDE123IJ' 
!SZ = 'ABC123' 



3.36 INTSET 



The INTSET function establishes a FORTRAN subroutine as an interrupt 
service routine, assigns it a priority, and attaches it to a vector. INTSET 
requires that extra memory be allocated to foreground programs that use it 
(see Section 1.2.4.1). 

Form: i = INTSET (vect,pri,id,crtn) 

where: 



vect 



pri 



id 



is the integer specifying the address of the interrupt vector to 
which the subroutine is to be attached 

is the integer specifying the actual priority level (4-7) at 
which the device interrupts 

is the identification integer to be passed as the single argu- 
ment to the FORTRAN routine when an interrupt occurs. 
This allows a single crtn to be associated with several INTSET 
calls 
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crtn is a FORTRAN subroutine to be established as the interrupt 
routine. This name should be specified in an EXTERNAL 
statement in the FORTRAN program that calls INTSET. The 
subroutine has one argument: 



SUBROUTINE crtn(id) 
INTEGER id 



When the routine is entered, the value of the integer argu- 
ment is the value specified for id in the appropriate INTSET 
call 

Notes: 

1. The id argument can be used to distinguish between interrupts from 
different vectors if the routine to be activated services multiple devices. 

2. When using INTSET in FB or XM, the SYSLIB call DEVICE must be 
used in almost all cases to prevent interrupts from interrupting beyond 
program termination. 

3. If the interrupt routine (crtn) has control for a period of time longer 
than the time in which two more interrupts using the same vector 
occur, interrupt overrun is considered to have occurred. The error mes- 
sage: 

?SYSLIB-F-Interrupt overrun 

is printed and the job is aborted. Jobs requiring very fast interrupt 
response are not viable with FORTRAN, since FORTRAN overhead 
lowers RT-ll's interrupt response rate. 

4. The interrupt routine (crtn) is actually run as a completion routine by 
the RT-11 .SYNCH macro. The pri argument is used for the RT-11 
.INTEN macro. 

5. A .PROTECT request is issued for the vector, but no attempt is made to 
report an error if the vector is already protected; furthermore, the vec- 
tor is taken over unconditionally. See the .PROTECT programmed re- 
quest (Section 2.60) for more information. 

6. The FORTRAN interrupt service subroutine (crtn) cannot call the USR. 

7. INTSET cannot be called from a completion or interrupt routine. 

8. Interrupt enable should not be set on the associated device until the 
INTSET call has been successfully executed. 



Errors: 



= Normal return. 

= 1 Invalid vector specification. 

= 2 Reserved for future use. 

= 3 No space is available for the linkage setup. 
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Example: 

EXTERNAL CLKSUB ! SUBR TO HANDLE Kkll-P CLOCK 



I=INTSET("104.G»0»CLKSUB) lATTACH ROUTINE 
IF (I.NE.O) GOTO 100 (BRANCH IF ERROR 



END 

SUBROUTINE CLKSUB(ID) 



END 

3.37 IPEEK 

The IPEEK function returns the contents of the word located at a specified 
absolute 16-bit memory address. This function can examine device registers 
or any location in memory. 

Form: i = IPEEK (iaddr) 

where: 

iaddr is the integer specification of the absolute address to be exa- 
mined. If this argument is not an even value, a trap results 
(except on LSI-11 or a PDP-11/23) 

Function Result: 

The function result (0 is set to the value of the word examined. 

Example: 

ISWIT = IPEEK( "177570) !GET VALUE OF CONSOLE SWITCHES 

3.38 IPEEKB 

The IPEEKB subroutine returns the contents of a byte located at a speci- 
fied absolute byte address. Since this routine operates in a byte mode, the 
address supplied can be odd or even. This subroutine can examine device 
registers or any byte in memory. The return is zero extended, that is, the 
high byte is 0. 

Form: i = IPEEKB (iaddr) 

where: 

iaddr is the integer specification of the absolute byte address to be 
examined. Unlike the IPEEK subroutine, the IPEEKB sub- 
routine allows odd addresses 

Function Result: 

The function result (i) is set to the value of the byte examined. 

Example: 

lERR = IPEEKB("53) !Get error b/te 
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3.39 IPOKE 



The IPOKE subroutine stores a specified 16- bit integer value into a speci- 
fied absolute memory location. This subroutine can store values in device 
registers. 

Form: CALL IPOKE (iaddr,ivalue) 
where: 



iaddr 



lvalue 



is the integer specification of the absolute address to be 
modified. If this argument is not an even value, a trap re- 
sults (except on LSI-11 or PDP-11/23) 

is the integer value to be stored in the given address speci- 
fied by the iaddr argument 



Errors: 

None. 
Example: 



The following example displays the value of IV AL in the console 
display register (this is possible only on certain processors). 

CALL IP0KE<"177570.I>.'AL) 

To set bit 12 in the JSW without zeroing any other bits in the JSW, 
use the following procedure. 

CALL I POKE ( "^4 »" 10000. OR. I PEEK ("44) > 



3.40 IPOKEB 



The IPOKEB subroutine stores a specified eight-bit integer value into a 
specified byte location. Since this routine operates in a byte mode, the 
address supplied can be odd or even. This subroutine can store values in 
device registers. 

Form: CALL IPOKEB (iaddr ,ivalue) 



where: 



iaddr is the integer specification of the absolute address to be 
modified. Unlike the IPOKE subroutine, the IPOKEB sub- 
routine allows odd addresses 

lvalue is the integer value to be stored in the given address speci- 
fied by the iaddr argument 



Errors: 

None. 
Example: 



CALL IPOKEB! "53 t"20) ! Tell KMDN unconditionally fatal error 
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3.41 IPUT 

The IPUT function replaces the value of a monitor fixed offset. IPUT uses 
the monitor .PVAL programmed request. 

Form: i - IPUT (ioff, value) 
where: 

ioff is the offset (from the base of RMON) to be modified 

value is the integer value to replace the current contents of the 
offset location 

Function Result: 

i = old (replaced) value of the fixed offset location. 

Example: 

ISIZE = IPUT ("314. 100) I Chanse default file size used by ENTER 

3.42 IQSET 

The IQSET function is used to make the RT-11 I/O queue larger — that is, 
to add available elements to the queue. These elements are allocated out of 
the free space managed by the FORTRAN system. IQSET cannot be called 
from a completion or interrupt routine. 

Form: i = IQSET (qleng[,area]) 

where: 

qleng is the integer number of elements to be added to the queue. 
This argument must be positioned so that the USR does not 
swap over it 

area is the space allocated from within the calling program. Un- 
der FB and SJ monitors, make sure that the space is outside 
the USR swapping area. If this argument is not specified, the 
space for the elements is allocated in the FORTRAN OTS 
work area 

All RT-11 I/O transfers are done through a centralized queue management 
system. If I/O traffic is very heavy and not enough queue elements are 
available, the program issuing the I/O requests is suspended until a queue 
element becomes available. In an FB or XM system, the other job can run 
while the first program waits for the element. When IQSET is used in a 
program to be run in the foreground, the FRUN command must be modified 
to allocate space for the queue elements (see Section 1.2.4.1). 

A general rule to follow is that each program should contain one more 
queue element than the total number of I/O and timer requests that will be 
active simultaneously. Timing functions such as ITWAIT and MRKT also 
cause elements to be used and must be considered when allocating queue 
elements for a program. Note that if synchronous I/O is done (for example, 
IREADW/IWRITW) and no timing functions are done, no additional queue 
elements need be allocated. Note also that FORTRAN IV allocates four 
queue elements by default. 

3-32 System Subroutine Description and Examples 



The following subroutines require queue elements: 

IRCVD/IRCVDC/IRCVDF/IRCVDW ITIMER 
IREAD/IREADC/IREADF/IREADW ITWAIT 
ISCHED lUNTIL 

ISDAT/ISDATC/ISDATF/ISDATW IWRITE/IWRITC/IWRITF/IWRITW 
ISLEEP MRKT 

ISPFN/ISPFNC/ISFFNF/ISPFNW MWAIT 

For further information on adding elements to the queue, see the .QSET 
programmed request. 

Errors: 

i = Normal return. 
= 1 Not enough free space is available for the number of 
queue elements to be added; no allocation was made. 

Example: 

IF(I0SET(5) .NE.O) STOP 'NOT ENOUGH FREE SPACE FOR QUEUE ELEMENTS' 

3.43 IRAD50 

The IRAD50 function converts a specified number of ASCII characters to 
Radix-50 and returns the number of characters converted. Conversion 
stops on the first non-Radix-50 character encountered in the input, or when 
the specified number of ASCII characters have been converted. 

Form: n = IRAD50 (icnt,input,output) 

where: 

n is the integer number of input characters actually con- 

nected 
icnt is the number of ASCII characters to be converted 

input is the area from which input characters are taken 
output is the area in which Radix-50 words are stored 

Three characters of text are packed into each word of output. The number 
of output words modified is computed by the expression (in integer words): 

(icnt + 2)/3 
Thus, if a count of 4 is specified, two words of output are written even if 
only a one-character input string is given as an argument. 

Function Result: 

The integer number of input characters actually converted (n) is returned 

as the function result. 

Example: 

REAL*8 FBPEC 

CALL IRAD50(12»'SY0TEMP DAT'.FSPEC) 

3.44 IRCVD/IRCVDC/IRCVDF/IRCVDW (FB and XM Only) 

There are four forms of the receive data function; these are used in conjunc- 
tion with the ISDAT (send data) functions to allow a general data/message 
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transfer system. The receive data functions issue RT-11 receive data pro- 
grammed requests (see Section 2.66). These functions require a queue ele- 
ment; this should be considered when the IQSET function (Section 3.42) is 
executed. 

IRCVD 

The IRCVD function receives data and continues execution. The operation 

is queued and the issuing job continues execution. When the job has to 

receive the transmitted message, an MWAIT should be executed. This 

causes the job to be suspended until all pending messages have been 

received. 

Form: i = IRCVD (buff,wcnt) 

where: 

buff is the array to be used to buffer the data received. The array 
must be one word larger than the message to be received 
because the first word contains the integer number of words 
actually transmitted when IRCVD is complete 

went is the maximum integer number of words that can be 
received 

Errors: 

i = Normal return. 
= 1 No such job exists in the system. (A job exists as long as it 
is loaded, whether or not it is active.) 

Example: 

INTEGER#2 MSG(41) 



CALL IRCyD(MBG.aO) 



CALL MWAIT 

IRCVDC 

The IRCVDC function receives data and enters an assembly language com- 
pletion routine when the message is received. The IRCVDC is queued, and 
program execution stays with the issuing job. When the other job sends a 
message, the completion routine specified is queued and run according to 
standard scheduling of completion routines. 

Form: i = IRCVDC (buflf,wcnt,crtn) 

where: 

buff is the array to be used to buffer the data received. The array 
must be one word larger than the message to be received be- 
cause the first word contains the integer number of words 
actually transmitted when IRCVDC is complete 
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went is the maximum integer number of words to be received 

crtn is the assembly language completion routine to be entered. 
This name must be specified in a FORTRAN EXTERNAL 
statement in the routine that issues the IRCVDC call 

Errors: 

i = Normal return. 

= 1 No such job exists in the system. (A job exists as long as it 
is loaded, whether or not it is active.) 

IRCVDF 

The IRCVDF function receives data and enters a FORTRAN completion 
subroutine when the message is received. The IRCVDF is queued, and pro- 
gram execution continues with the issuing job. When the other job sends a 
message, the FORTRAN completion routine specified is entered. 

Form: i = IRCVDF (buff,wcnt,area,crtn) 

where: 

buff is the array to be used to buffer the data received. The array 
must be one word larger than the message to be received 
because the first word contains the integer number of words 
actually transmitted when IRCVDF is complete 

went is the maximum integer number of words to be received 

area is a four-word area to be set aside for linkage information. 
This area must not be modified by the FORTRAN program 
and the USR must not swap over it. This area can be re- 
claimed by other FORTRAN completion routines when crtn 
has been entered 

crtn is the FORTRAN completion routine to be entered. This name 
must be specified in an EXTERNAL statement in the FOR- 
TRAN routine that issues the IRCVDF call 



Errors: 



i = Normal return. 
= 1 No such job exists in the system. (A job exists as long as it 
is loaded, whether or not it is active.) 



Example: 



INTEGER*2 MSG ( ill ) f AREA ( fl ) 
EXTERNAL RMSGRT 



CALL IRCVDF(MSGi40.AREA tRMSGRT) 



IRCVDW 

The IRCVDW function receives data and waits. This function queues a 

message request and suspends the job issuing the request until the other 
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job sends a message. When execution of the issuing job resumes, the mes- 
sage has been received, and the first word of the buffer indicates the num- 
ber of words transmitted. 

Form: i = IRCVDW (buff,wcnt) 

where: 

buff is the array to be used to buffer the data received. The array 
must be one word larger than the message to be received 
because the first word contains the integer number of words 
actually transmitted when IRCVDW is complete 

went is the maximum integer number of words to be received 

Errors: 

i = Normal return. 
= 1 No such job exists in the system. (A job exists as long as it 
is loaded, whether or not it is active.) 

Example: 

INTEGER*2 MSG(^l) 

IF(IRCyDW(MSG .40) .NE.O) STOP 'UNEXPECTED ERROR' 

3.45 IREAD/IREADC/IREADF/IREADW 

The functions IREAD, IREADC, IREADF, and IREADW transfer a speci- 
fied number of words from a file into memory. These functions require a 
queue element, which should be considered when the IQSET function (Sec- 
tion 3.42) is executed. 

IREAD 

The IREAD function transfers into memory a specified number of words 
from the file associated with the indicated channel. Control returns to the 
user program immediately after the IREAD function is initiated. No special 
action is taken when the transfer is completed. 

Form: i - IREAD (wcnt,buff,blk,chan) 

where: 

went is the relative integer number of words to be transferred 

buff is the array to be used as the buffer; this array must contain 
at least went words 

blk is the integer block number of the file to be read. The first 
block of a file is block number 0. The blk argument must be 
updated when necessary. For example, if the program is read- 
ing two blocks at a time, blk should be updated by 2 

chan is the integer specification for the RT-11 channel to be used 

When the user program needs to access the data read on the specified 
channel, an IWAIT function should be issued. This makes sure that the 
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IRE AD operation has been completed. If an error occurred during the trans- 
fer, the IWAIT function indicates the error. 



Errors: 

i = n 



Normal return; n equals the number of words requested (0 
for non-file-structured read, multiple of 256[decimal] for 
file-structured read). If the read is from a magtape, the 
number of words requested is returned. For example: 

If went is a multiple of 256 and less than that number 
of words remain in the file, n is shortened to the num- 
ber of words that remain in the file; thus, if went is 512 
and only 256 words remain, i = 256. 

If went is not a multiple of 256 and more than went 
words remain in the file, n is rounded up to the next 
block; thus, if went is 312 and more than 312 words 
remain, i - 512, but only 312 are read. 

If went is not a multiple of 256 and less than went 
words remain in the file, n equals a multiple of 256 that 
is the actual number of words being read. 

= -1 Attempt to read past end-of-file; no words remain in the file. 
= -2 Hardware error occurred on channel. 
= -3 Specified channel is not open. 

NOTE 

If an asynchronous operation on a channel (for example, 
IREAD) results in end-of-file, the following IWAIT will not 
detect it. IWAIT detects only hard error conditions. A subse- 
quent operation on that channel will detect end-of-file and 
returns to the user with the end-of-file error code. Under 
these conditions, the subsequent operation is not initiated. 



Example: 



INTEGER*2 BUFFER(Z5G) ,RCDDE tBLK 



RCODE = IREAD(25B (BUFFER »BLK tICHAN) 

IF(RC0DE+1) lOlOflOOO.lO 
C IF ND ERROR. START HERE 
10 



IFdWAITdCHAN) .NE.O) GOTO 1010 



1000 CONTINUE 

C END OF FILE PROCESSING 



CALL EXIT ! NORMAL END OF PROGRAM 

1010 STOP 'FATAL READ' 
END 
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IREADC 

The IREADC function transfers a specified number of words from the indi- 
cated channel into memory. Control returns to the user program immedi- 
ately after the IREADC function is initiated. When the operation is com- 
plete, the specified assembly language routine {crtn) is entered as an asyn- 
chronous completion routine. 

Form: i = IREADC (wcnt,buff,blk,chan,crtn) 
where: 



went 
buff 

blk 

chan 
crtn 



is the integer number of words to be transferred 

is the array to be used as the buffer; this array must contain 
at least went words 

is the integer block number of the file to be read. The user 
program normally updates hlk before it is used again. The 
first block of a file is block number 

is the integer specification for the RT-11 channel to be used 

is the assembly language routine to be activated when the 
transfer is complete. This name must be specified in an EX- 
TERNAL statement in the FORTRAN routine that issues the 
IREADC call 

Errors: 

See the errors under IREAD. 

Example: 

INTEGER*2 IBUF ( 256 ) tRCDDE . IBLK 
EXTERNAL RDCMP 

t 

* 

RC0DE=IREADC(25B»IBUF,IBLK , I CHAN , RDCMP ) 

IREADF 

The IREADF function transfers a specified number of words from the indi- 
cated channel into memory. Control returns to the user program immedi- 
ately after the IREADF function is initiated. When the operation is com- 
plete, the specified FORTRAN subprogram {.crtn) is entered as an asynchro- 
nous completion routine (see Section 1.2.1.2). 

Form: i = IREADF (wcnt,buff,blk,chan,area,crtn) 
where: 

went is the integer number of words to be transferred 

buff is the array to be used as the buffer; this array must contain 
at least went words 

blk is the integer block number of the file to be used. The user 
program normally updates blk before it is used again. The 
first block of a file is block number 
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chan is the integer specification for the RT-11 channel to be used 

area is a four-word area to be set aside for link information; this 
area must not be modified by the FORTRAN program or 
swapped over by the USR. This area can be reclaimed by 
other FORTRAN completion functions when crtn has been 
activated 

crtn is the FORTRAN routine to be activated on completion of the 
transfer. This name must be specified in an EXTERNAL 
statement in the routine that issues the IREADF call. Section 
1.2.1.2 describes completion routines 

Errors: 

See the errors under IRE AD. 

Example: 

INTEGER*2 DBLK<a) ,BUFFER(25G) .BLKNO 

DATA DBLK/3RDX0 t3RINP (3RUT tSRDAT/ iBLKND/O/ 

EXTERNAL RCMPLT 



ICHAN=IGETC( ) 

IF(ICHAN.LT.O) STOP 'NO CHANNEL AVAILABLE' 
IF(IFETCH(DBLK) .NE.O) STOP 'BAD FETCH' 
IF(LOOKUP( ICHANfDBLK) .LT.O) STOP 'BAD LOOKUP' 



20 IF(IREADF(25B»BUFFER»BLKN0»ICHAN»DBLK .RCMPLT) .LT.O) GOTO 

100 

C PERFORM OVERLAP PROCESSING 



SYNCHRONIZER 

CALL IWAIT(ICHAN) IWAIT FOR COMPLETION ROUTINE TO RUN 

BLKN0=BLKN0+1 lUPDATE BLOCK NUMBER 

GOTO 20 



C END OF FILE PROCESSING 
100 CALL ICLOSEdCHAN.I) 

I=ICLOSE( ) 

CALL IFREEC(ICHAN) 



CALL EXIT 
END 

SUBROUTINE RCMPLTd .J) 
C THIS IS THE COMPLETION ROUTINE 



RETURN 
END 
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IREADW 

The IREADW function transfers a specified number of words from the indi- 
cated channel into memory. Control returns to the user program when the 
transfer is complete or when an error is detected. 

Form: i = IREADW (wcnt,buff,blk,chan) 

where: 

went is the integer number of words to be transferred 

buff is the array to be used as the buffer; this array must contain 
at least went words 

blk is the integer block number of the file to be read. The user 
program normally updates hlk before it is used again 

chan is the integer specification for the RT-11 channel to be used 
Errors: 

See the errors under IREAD. 
Example: 

INTEGER*2 IBUF(102^) 



I CODE = IREADW (1024 »IBUF ,IBLK » I CHAN) 

IF(IC0DE.E0.-1 ) GOTO 100 ! END OF FILE PROCESSING AT 100 

IF( ICODE.LT.-l ) GOTO 200 ! ERROR PROCESSING AT 200 

C 

C MODIFY BLOCKS 

C 



C 

C WRITE THEM OUT 

C 

ICDDE=IWRITW(102'a.IBUF»IBLK , I CHAN) 



3.46 IRENAM 



The IRENAM function causes an immediate change of the name of a speci- 
fied file. 

Form: i = IRENAM (chan,dblk) 

where: 

chan is the integer specification for the RT-11 channel to be used 
for the operation. You must obtain this channel through an 
IGETC call, or you can use channel 16(decimal) or higher if 
you have done an ICDFN call. The channel is again available 
for use once the rename operation is completed 

dblk is the eight-word area specifying the name of the existing file 
and the new name to be assigned. If considered as an eight- 
element INTEGER*2 array, dhlk has the form: 
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Words 1-4 specify the Radix-50 file descriptor for the old 
file name 

Words 5-8 specify the Radix-50 file descriptor for the 
new file name 

NOTE 

The arguments of IRENAM must be positioned so that the 
USR does not swap over them. 

If a file already exists with the same name as the new file on the indicated 
device, it is deleted. IRENAM requires that the handler to be used be resi- 
dent at the time the IRENAM is issued. If it is not, a monitor error occurs. 
The device names specified in the file descriptors must be the same. 

For more information on renaming files, see the .RENAME programmed 
request (Section 2.71). 



Errors: 



= Normal return. 

= 1 Specified channel is already open. 

= 2 Specified file was not found. 

= 3 A file by that name already exists and is protected. 



Example: 



REAL*B NAME(2) 

DATA NAME/12RDK0FTN2 DAT . 12RDK0FTN2 OLD/ 



ICHAN=IGETC( ) 

IF( ICHAN.LT.O) STOP 'NO CHANNEL' 

CALL IRENAMdCHAN tNAME) ! PRESERVE OLD DATA FILE 

CALL IFREEC(ICHAN) 



3.47 IREOPN 



The IREOPN function reassociates a specified channel with a file on which 
an ISAVES was performed. The ISAVES/IREOPN combination is useful 
when a large number of files must be operated on at one time. Necessary 
files can be opened with LOOKUP and their status preserved with 
ISAVES. When data is required from a file, an IREOPN enables the pro- 
gram to read from the file. The IREOPN need not be done on the same 
channel as the original LOOKUP and ISAVES. 

Form: i = IREOPN (chan.cblk) 

where: 

chan is the integer specification for the RT-11 channel to be asso- 
ciated with the reopened file; this channel must be initially 
inactive 
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cblk is the five-word block where the channel status information 
was stored by a previous ISAVES. This block, considered as a 
five-element INTEGER*2 array, has the following format: 

Word 1 Channel status word. 

2 Starting block number of the file; zero for non- 
file-structured devices. 

3 Length of file (in 256-word blocks). 

4 Reserved for future use. 

5 Two information bytes. Even byte: I/O count of 
the number of requests outstanding on this chan- 
nel. Odd byte: unit number of the device associ- 
ated with the channel. 



Errors: 



i = Normal return. 
= 1 Specified channel is already in use. 



Example: 



INTEGER*2 SAVES(5»10) 
DATA ISVPTR/1/ 



CALL I SAVES ( I CHAN tSAVESC 1 dSVPTR) ) 



CALL IREOPN( ICHAN.SAMES( 1 .ISUPTR) ) 



3.48 ISAVES 



The ISAVES function stores five words of channel status information into a 
user-specified array. These words contain all the information that RT-11 
requires to completely define a file. When an ISAVES is finished, the data 
words are placed in memory and the specified channel is closed, so that it is 
again available for use. When the saved channel data is required, the IRE- 
OPN function (Section 3.47) is used. 

ISAVES can be used only if a file was opened with a LOOKUP call (see 
Section 3.79). If lENTER was used, ISAVES returns an error. Note that 
ISAVES is not legal on magtape or cassette files. 

Form: i = ISAVES (chan,cblk) 

where: 

chan is the integer specification for the RT-11 channel whose 
status is to be saved. You must obtain this channel through 
an IGETC call, or you can use channel 16 or higher if you 
have done an ICDFN call 

cblk is a five-word block in which the channel status information 
describing the open file is stored (see Section 3.47 for the 
format of this block). 
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The ISAVES/IREOPN combination is very useful, but care must be ex- 
ercised when using it. In particular, the following cases should be avoided. 

1. If an ISAVES is performed on a file and the same file is then 
deleted before it is reopened, the space occupied by the file be- 
comes available as an empty space which could then be used by 
the lENTER function. If this sequence occurs, there is a change in 
the contents of the file whose status was supposedly saved. 

2. Although the handler for the required peripheral need not be in 
memory for execution of an IREOPN, a fatal error is generated if 
the handler is not in memory when an IREAD or IWRITE is 
executed. 

Errors: 

i = Normal return. 
= 1 The specified channel is not currently associated with any 

file. 
= 2 The file was opened with an lENTER call. 

Example: 

INTEGER*Z BLK(5) 



IF(ISAVES( ICHANtBLK) .NE,0) STOP 'ISAMES ERROR' 



3.49 ISCHED 



The ISCHED function schedules a specified FORTRAN subroutine to be 
run as an asynchronous completion routine at a specified time of day. Sup- 
port for ISCHED in SJ requires timer support. 

Form: i = ISCHED (hrs,min,sec,tick,area,id,crtn) 

where: 

hrs is the integer number of hours 

min is the integer number of minutes 

sec is the integer number of seconds 

tick is the integer number of ticks (1/60 of a second on 60-cycle 
clocks; 1/50 of a second on 50-cycle clocks) 

area is a four-word area that must be provided for link informa- 
tion; this area must never be modified by the FORTRAN pro- 
gram, and the USR must not swap over it. This area can be 
reclaimed by other FORTRAN completion functions when 
crtn has been activated 

id is the identification integer to be passed to the routine being 

scheduled 
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crtn is the name of the FORTRAN subroutine to be entered at the 
time of day specified. This name must be specified in an EX- 
TERNAL statement in the FORTRAN routine that issues the 
ISCHED call. The subroutine has one argument. For exam- 
ple: 

SUBROUTINE crtn(id) 
INTEGER id 

When the routine is entered, the value of the integer argu- 
ment is the value specified for id in the appropriate ISCHED 
call 



Notes: 

1. The scheduling request made by ISCHED can be canceled at a later 
time by an ICMKT function call. 

2. If the system is busy, the actual time of day that the completion routine 
is run may be later than the requested time of day. 

3. A FORTRAN subroutine can periodically reschedule itself by issuing 
its own ISCHED or ITIMER calls from within the routine. 

4. ISCHED requires a queue element; this should be considered when the 
IQSET function (Section 3.42) is executed. 

Errors: 

i - Normal return. 
= 1 No queue elements available; unable to schedule request. 

Example: 

INTEGER*2 LINK<4) (LINKAGE AREA 

EXTERNAL NOON ! NAME OF ROUTINE TO RUN 



I = ISCHED( 12.0.0(0 .LINK »0 tNOON) ! RUN SUBR NOON AT 12 PM 
I Crest of wain proSraitt) 

END 

SUBROUTINE NOONCID) 
C 

C THIS ROUTINE WILL TERMINATE EXECUTION AT LUNCHTIME. 
C IF THE JOB HAS NOT COMPLETED BY THAT TIME. 
C 

STOP 'ABORT JOB -- LUNCHTIME' 

END 

3.50 ISCOMP 

(See SYSLIB subroutine SCOMP.) 

3.51 ISDAT/ISDATC/ISDATF/ISDATW (FB and XM Only) 

The functions ISDAT, ISDATC, ISDATF, and ISDATW are used with the 
IRCVD, IRCVDC, IRCVDF, and IRCVDW calls to allow message transfers 
under the FB or XM monitor. Note that the buffer containing the message 
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should not be modified or reused until the message has been received by the 
other job. These functions require a queue element, which should be consid- 
ered when the IQSET function (see Section 3.42) is executed. 

ISDAT 

The ISDAT function transfers a specified number of words from one job to 
the other. Control returns to the user program immediately after the trans- 
fer is queued. This call is used with the MWAIT routine (see Section 3.90). 

Form: i = ISDAT (buff, went) 

where: 

buff is the array containing the data to be transferred 

went is the integer number of data words to be transferred 

Errors: 

i = Normal return. 
= 1 No such job currently exists in the system. (A job exists as 
long is it is loadable, whether or not it is active.) 



Example: 



INTEGER*2 MSG(40) 



CALL ISDATCMSG tflO) 



CALL MWAIT 

PUT NEW MESSAGE IN BUFFER 



ISDATC 

The ISDATC function transfers a specified number of words from one job to 
another. Control returns to the user program immediately after the trans- 
fer is queued. When the other job accepts the message through a receive 
data request, the specified assembly language routine (crtn) is activated as 
an asynchronous completion routine. 

Form: i = ISDATC (buflf,wcnt,crtn) 

where: 

buff is the array containing the data to be transferred 

went is the integer number of data words to be transferred 

crtn is the name of an assembly language routine to be activated 
on completion of the transfer. This name must be specified in 
an EXTERNAL statement in the FORTRAN routine that is- 
sues the ISDATC call 



Errors: 



i = Normal return. 
= 1 No such job currently exists in the system. (A job exists as 
long as it is loaded, whether or not it is active.) 
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Example: 



INTEGER*2 MSG(40) 
EXTERNAL RTN 



CALL ISDATC(MSG.^OfRTN) 



ISDATF 

The ISDATF function transfers a specified number of words from one job to 
the other. Control returns to the user program immediately after the trans- 
fer is queued and execution continues. When the other job accepts the mes- 
sage through a receive data request, the specified FORTRAN subprogram 
icrtn) is activated as an asynchronous completion routine (see Section 
1.2.1.2). 

Form: i - ISDATF (buff,wcnt,area,crtn) 

where: 

buff is the array containing the data to be transferred 

went is the integer number of data words to be transferred 

area is a four-word area to be set aside for link information; this 
area must not be modified by the FORTRAN program and the 
USR must not swap over it. This area can be reclaimed by 
other FORTRAN completion functions when crtn has been 
activated 

crtn is the name of a FORTRAN routine to be activated on comple- 
tion of the transfer. This name must be specified in an EX- 
TERNAL statement in the FORTRAN routine that issues the 
ISDATF call 



Errors: 



i = Normal return. 
= 1 No such job currently exists in the system. (A job exists as 
long as it is loaded, whether or not it is active.) 



Example: 



INTEGER*2 MSG ( ^0) .SPOT ( 4 ) 
EXTERNAL RTN 



CALL ISDATFCMSG .aO .SPOT »RTN) 



ISDATW 

The ISDATW function transfers a specified number of words from one job to 
the other. Control returns to the user program when the other job has 
accepted the data through a receive data request. 

Form: i = ISDATW (buff.wcnt) 
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where: 

buff is the array containing the data to be transferred 
went is the integer number of data words to be transferred 

Errors: 

i = Normal return. 
= 1 No such job exists in the system. (A job exists as long as it is 
loaded, whether or not it is active.) 

Example: 

INTEGER*2 MSG(^O) 

f 
4 
« 

IF (ISDATW(MSG»40) .NE.O) STOP 'FOREGROUND JOB NOT RUNNING' 

3.52 ISDTTM 

The ISDTTM function sets the system date and time. An argument of -1 
leaves the corresponding value unchanged. 

Form: CALL ISDTTM (date,hitime,lotime) 
where: 

date is the new system date 

hitime is the high-order time of day, in ticks past midnight 

lotime is the low-order time of day, in ticks past midnight 
Example: 



C DEFINE NEW SYSTEM DATE BUT LEAME TIME UNCHANGED 
IDATE = IM0NTH*1024+IDAY*32+(IYEAR-197Z) 
CALL ISDTTM (IDATE» -1» -1) 



3.53 ISFDAT 



The ISFDAT function allows user programs to modify the creation date of 
an RT-11 file. The device must have an RT-11 file structure. 

Form: i = ISFDAT (chan,dblk,idate) 
where: 

chan is the integer value of the RT-11 channel to be used for the 
operation. You must obtain this channel through an IGETC 
call, or you can use channel 16(decimal) or higher if you have 
done an ICDFN call 
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dblk 

idate 
Errors: 



is the four word RT-11 file specification, in Radix-50, of the 
file whose date is being changed 

is the integer date in RT-11 date format 



= Normal return. 

= 1 Channel in use. 

== 2 File not found. 

= 3 Invalid operation. 



Example: 



This example changes the date of the file DY1:0LD23.DAT to July 4, 
1976. 

REAL#^ FILNAM(2) 

DATA FILNAM /6RDY1 OLD .GR23 DAT/ 

IDATE = 7»102il + a»32 + (1976-1972) ! JULY H, 197B 

ICHAN = IGETCO (ALLOCATE CHANNEL 

I = ISFDATdCHAN. FILNAM , IDATE) ! SET THE DATE 

IF (I.NE.O) STOP 'ERROR DURING ISFDAT CALL' 



END 



3.54 ISLEEP 



The ISLEEP function suspends the main program execution of a job for a 
specified amount of time. The specified time is the sum of hours, minutes, 
seconds, and ticks specified in the ISLEEP call. All completion routines 
continue to execute. 



Form: i = 

where: 
hrs 
min 
sec 
tick 

Notes: 



ISLEEP (hrs,min,sec,tick) 

is the integer number of hours 

is the integer number of minutes 

is the integer number of seconds 

is the integer number of ticks (1/60 of a second on 60-cycle 
clocks; 1/50 of a second on 50-cycle clocks) 



1. SLEEP requires a queue element, which should be considered when the 
IQSET function (Section 3.42) is executed. 

2. If the system is busy, the time in which execution is suspended may be 
later than that specified. 

Errors: 

i = Normal return. 
= 1 No queue element available. 
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Example: 



CALL IQSEKZ) 



CALL ISLEEP(0 »0»0»^> !GIVE BACKGROUND JOB SOME TIME 



3.55 ISPFN/ISPFNC/ISPFNF/ISPFNW 

The functions ISPFN, ISPFNC, ISPFNF, and ISPFNW are used in conjunc- 
tion with special functions to various handlers. They provide a means of 
doing device-dependent functions, such as rewind and backspace, to those 
devices. If ISPFN function calls are made to any other devices, the function 
call is ignored. For more information on programming for specific devices, 
see the RT—11 Software Support Manual. 

To use these functions, the handler must be in memory, and a channel must 
be associated with a file via a non-file-structured LOOKUP call. These 
functions require a queue element; this should be considered when the 
IQSET function (Section 3.42) is executed. 

ISPFN 

The ISPFN function queues the specified operation and immediately re- 
turns control to the user program. The IWAIT function can be used to 
ensure completion of the operation. 

Form: i = ISPFN (code,chan[,wcnt,buff,blk]) 

where: 

code is the integer numeric code of the function to be performed 
(see Table 3-1) 

chan is the integer specification for the RT-11 channel to be used 
for the operation. You must obtain this channel through an 
IGETC call, or you can us© channel l&(;decimal) or higher if 
you have- done am ICDFN call 

went is the integer number of data words in the operation. This 
parameter is optional with some ISPFN calls, depending on 
the particular function. Default value is 0. In magtape opera- 
tions, it specifies the number of records to space forward or 
backward. For a backspace operation iwcnt = 0), the tape drive 
backspaces to a tape mark or to the beginning-of-tape. For a 
forward space operation iwcnt=0), the tape drive forward 
spaces to a tape mark or the end-of-tape 

buff is the array to be used as the data buffer. This parameter is 
optional with some ISPFN calls, depending on the particular 
function. Default value is 
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blk is the integer block number of the file to be operated upon. 
This parameter is optional with some ISPFN calls, depending 
on the particular function. Default value is 

When this argument is supplied by magtape, it is the address 
of a four-word error and status block used for returning the 
exception conditions. The four words must be initialized to 
zero. 

The error and status block must always be mapped when run- 
ning in the XM monitor, and the USR must not swap over it. 
To obtain the address of the error block, execute the following 
instructions: 

INTEGER*Z ERRADR, ERRBLK(4) 
DATA ERRBLK /O .0 lOiO./ 



ERRADR = lADDR (ERRBLK) ! GET THE ADDRESS OF THE fl-WORD ERROR BLOCK 
ICODE = ISPFN (CODE. ICHANiWDCT.BUF. ERRADR) 

The three optional arguments {went, huff, blk) are not individually op- 
tional. You must have all or none present. 
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Errors: 



i = 

= 1 

= 2 

= 3 



Normal return. 

Attempt to read or write past end-of-file. 
Hardware error occurred on channel. 
Channel specified is not open. 



Example: 

CALL ISPFN( "373 tICHAN) 



IREWIND 



ISPFNC 

The ISPFNC function queues the specified operation and immediately re- 
turns control to the user program. When the operation is complete, the 
specified assembly language routine {crtn) is entered as an asynchronous 
completion routine. 

Form: i = ISPFNC (code,chan,wcnt,buff,blk,crtn) 

where: 

code is the integer numeric code of the function to be performed 
(see Table 3-1) 

chan is the integer specification for the RT-11 channel to be used 
for the operation. You must obtain this channel through an 
IGETC call, or you can use channel 16(decimal) or higher if 
you have done an ICDFN call 

went is the integer number of data words in the operation; the de- 
fault value for this argument is 

buff is the array to be used as the data buffer; the default value for 
this argument is 

blk is the integer block number of the file to be operated upon; 
this argument must be if riot required 

When this argument is supplied by magtape, it is the address 
of a four-word error and status block used for returning the 
exception conditions. The four words must be initialized to 0. 

The error and status block must always be mapped when run- 
ning in the XM monitor, and the USR must not swap over it. 
To obtain the address of the error block execute the following 
instructions: 



INTEGER#2 
DATA ERRBLK 



ERRADR , ERRBLK(a) 
/ 1 » » » / 



!GET ADDRESS OF a-WORD ERROR BLOCK 

ERRADR = lADDR (ERRBLK) 

ICODE = ISPFNC (CODE tICHAN »WDCT»BUF tERRADR) 
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crtn is the name of an assembly language routine to be activated 
on completion of the operation. This name must be specified 
in an EXTERNAL statement in the FORTRAN routine that 
issues the ISPFNC call 



Errors: 



i = 

= 1 

= 2 

- 3 



Example: 



Normal return. 

Attempt to read or write past end-of-file. 
Hardware error occurred on channel. 
Channel specified is not open. 



EXTERNAL SFCDMP 



!NAME OF ASSEMBLY LANGUAGE COMPLETION RTN 



ICODE = IBPFNC(CODE (ICHAN tWDCT »BUF »BLK .SFCOMP) 

ISPFNF 

The ISPFNF function queues the specified operation and immediately re- 
turns control to the user program. When the operation is complete, the 
specified FORTRAN subprogram (crtn) is entered as an asynchronous com- 
pletion routine. 

Form: i = ISPFNF (code,chan,wcnt,buff,blk,area,crtn) 

where: 

code is the integer numeric code of the function to be performed 
(see Table 3-1) 

chan is the integer specification for the RT-11 channel to be used 
for the operation. You must obtain this channel through an 
IGETC call, or you can use channel 16(decimal) or higher if 
you have done an ICDFN call 

went is the integer number of data words in the operation; this 
argument must be if not required 

buff is the array to be used as the data buffer; this argument must 
be if not required 

blk is the integer block number of the file to be operated upon; 
this argument must be if not required 

When this argument is supplied by magtape, it is the address 
of a four-word error and status block used for returning the 
exception conditions. The four words must be initialized to 0. 

The error and status block must always be mapped when 
running in the XM monitor, and the USR must not swap over 
it. To obtain the address of the error block, execute the fol- 
lowing instructions: 
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INTEGER*2 
DATA ERRBLK 



ERRADR , ERRBLK(4) 
/O .0 (0 .0 t/ 



!GET THE ADDRESS OF THE il-WORD ERROR BLOCK 

ERRADR = lADDR (ERRBLK) 

ICODE = ISPFNF (CODE fICHAN tWDCT »BUF »ERRADR) 

area is a four-word area to be set aside for linkage information; 
this area must not be modified by the FORTRAN program, 
and the USR must not swap over it. This area can be re- 
claimed by other FORTRAN completion functions when crtn 
has been activated 

crtn is the name of a FORTRAN routine to be activated on com- 
pletion of the operation. This name must be specified in an 
EXTERNAL statement in the FORTRAN routine that issues 
the ISPFNF call (Section 1.2.1.2 describes completion 
routines) 



Errors: 



1 = 



Normal return. 

1 Attempt to read or write past end-of-file. 

2 Hardware error occurred on channel. 

3 Channel specified is not open. 



Example: 



REAL#4 MTNAHE(Z) »AREA(Z) 
DATA MTNAME/3RMT0 tO./ 
EXTERNAL DONSUB 



I = IGETC( ) 

CALL IFETCH(MTNAME) 
CALL LOOKUPd tMTNAME) 
IERR=ISPFNF( "373*1 »OtO 



! ALLOCATE CHANNEL 
IFETCH MT HANDLER 
INON-FILE-STRUCTURED LOOKUP ON 
»AREA tDONSUB) IREWIND MAGTAPE 



MTO 



END 

SUBROUTINE DONSUB 

RUNS WHEN MTO HAS BEEN REWOUND 



END 



ISPFNW 

The ISPFNW function queues the specified operation and returns control to 

the user program when the operation is complete. 



Form: 



ISPFNW (code,chan[,wcnt,buflf,blk]) 
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where: 



code is the integer numeric code of the function to be performed 
(see Table 3-1) 

chan is the integer specification for the RT-11 channel to be used 
for the operation. You must obtain this channel through an 
IGETC call, or you can use channel 16(decimal) or higher if 
you have done an ICDFN call 

went is the integer number of data words in the operation. This 
parameter is optional with some ISPFNW calls, depending on 
the function 

buff is the array to be used as the data buffer. This parameter is 
optional with some ISPFNW calls, depending on the function 

blk is the integer block number of the file to be operated upon. 
This parameter is optional with some ISPFNW calls, depend- 
ing on the function 

When this argument is supplied by magtape, it is the address 
of a four-word error and status block used for returning the 
exception conditions. The four words must be initialized to 0. 

The error and status block must always be mapped when 
running in the XM monitor, and the USR must not swap over 
it. To obtain the address of the error block execute the follow- 
ing instructions: 



INTEGER*2 
DATA ERRBLK 



ERRADR » ERRBLK (4) 
/O »0 »0 tO»/ 



Errors: 



Example: 



!GET THE ADDRESS OF THE 4-WORD ERROR BLOCK 

ERRADR = lADDR (ERRBLK) 

ICODE = ISPFN (CODE (ICHAN »WDCT »BUF tERRADR) 



i = Normal return. 

= 1 Attempt to read or write past end-of-file. 

= 2 Hardware error occurred on channel. 

= 3 Channel specified is not open. 



INTEGER#2 BUF(B5) .TRACK .SECTOR tDBLK(4) 
DATA DBLK/3RDX0 .0 .0 .0/ 



ICHAN=IGETC( ) 

IF{ ICHAN.LT.O) STOP 'NO CHANNEL AVAILABLE' 

IF(LOOKUP(ICHAN tDBLK) .LT.O) STOP 'BAD LOOKUP' 



READ AN ABSOLUTE TRACK AND SECTOR FROM THE FLOPPY 
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c 
c 
c 



ICDDE=ISPFNW( "377 »ICHAN tTRACK »BUF tSECTOR) 

BUF(l) IB THE DELETED DATA FLAG 
BUF(2-B5> IS THE DATA 



3.56 ISPY 



The ISPY function returns the integer value of the word at a specified offset 
from the RT-11 resident monitor. This subroutine uses the .GVAL pro- 
grammed request to return fixed monitor offsets. (See the RT—11 Software 
Support Manual for information on fixed offset references.) 

Form: i - ISPY (ioff) 

where: 

ioff is the offset (from the base of RMON) to be examined 

Function Result: 

The function result (i) is set to the value of the word examined. 

Example: 



c 
c 

c 

c 
c 
c 



BRANCH TO 200 IF RUNNING UNDER FB MONITOR 

IF( ISPY( "300) .AND. 1 ) GOTO 200 

WORD AT OCTAL 300 FROM RMON IS 
THE CONFIGURATION WORD. 



3.57 ITIMER 



The ITIMER function schedules a specified FORTRAN subroutine to be run 
as an asynchronous completion routine after a specified time interval has 
elapsed. This request is supported by SJ when the timer support special 
feature is included during system generation. 

Form: i = ITIMER (hrs,min,sec,tick,area,id,crtn) 

where: 



hrs 
min 
sec 
tick 

area 



id 



crtn 



is the integer number of hours 

is the integer number of minutes 

is the integer number of seconds 

is the integer number of ticks (1/60 of a second on 60-cycle 
clocks; 1/50 of a second on 50-cycle clocks) 

is a four-word area that must be provided for link informa- 
tion; this area must never be modified by the FORTRAN pro- 
gram, and the USR must never swap over it. This area can be 
reclaimed by other FORTRAN completion functions when 
crtn has been activated 

is the identification integer to be passed to the routine being 
scheduled 

is the name of the FORTRAN subroutine to be entered when 
the specified time interval elapses. This name must be speci- 
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fied in an EXTERNAL statement in the FORTRAN routine 
that references ITIMER. The subroutine has one argument. 
For example: 

SUBROUTINE crtn(id) 
INTEGER id 

When the routine is entered, the value of the integer argu- 
ment is the value specified for id in the appropriate ITIMER 
call 
Notes: 

1. This function can be canceled at a later time by an ICMKT function 
call. 

2. If the system is busy, the actual time interval after which the comple- 
tion routine is run can be longer than the time interval requested. 

3. FORTRAN subroutines can periodically reschedule themselves by issu- 
ing ISCHED or ITIMER calls. 

4. ITIMER requires a queue element, which should be considered when 
the IQSET function (Section 3.42) is executed. 

For more information on scheduling completion routines, see Section 
1.2.1.2 and the .MRKT programmed request. Section 2.45. 

Errors: 

i = Normal return. 
= 1 No queue elements available; unable to schedule request. 

Example: 

INTEGER*2 AREA(4) 
EXTERNAL WATCHD 



C IF THE CODE FOLLOWING ITIMER DOES NOT REACH THE ICMKT CALL 
C IN 12 MINUTES, WATCH DOG COMPLET ION , ROUT INE WILL BE 
C ENTERED WITH ID OF 3 
C 

CALL ITIMER (0,1 2,0 ,0 ,AREA ,3 , WATCHD) 



CALL ICMKTO ,AREA) 



END 

SUBROUTINE WATCHD(ID) 
C 
C THIS IS CALLED AFTER 12 MINUTES 



RETURN 
END 
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3.58 ITLOCK (FB and XM Only) 

The ITLOCK function is used in an FB or XM system to attempt to gain 
ownership of the USR. It is similar to LOCK (Section 3.78) in that, if suc- 
cessful, the user job returns with the USR in memory. However, if a job 
attempts to LOCK the USR while the other job is using it, the requesting 
job is suspended until the USR is free. With ITLOCK, if the USR is not 
available, control returns immediately and the lock failure is indicated. 
ITLOCK cannot be called from a completion or interrupt routine. 

Form: i = ITLOCKO 

For further information on gaining ownership of the USR, see the .TLOCK 
programmed request (Section 2.88). 

Errors: 

i = Normal return. 
= 1 USR is already in use. 

Example: 

IFdTLOCKO .NE.O) GOTO 100 !GOTO 100 IF USR BUSY 

3.59 ITTINR 

The ITTINR function transfers a character from the console terminal to the 
user program. If no characters are available, system action is determined 
by the setting of bit 6 of the Job Status Word. 

Form: i = ITTINRO 

If the function result (i) is less than when execution of the ITTINR func- 
tion is complete, it indicates that no character was available. Under the FB 
or XM monitor, ITTINR does not return a result of less than zero unless bit 
6 of the Job Status Word was on when the request was issued. 

There are two modes of doing console terminal input, and they are gov- 
erned by bit 12 of the Job Status Word (JSW). The JSW is at octal location 
44. Jf bit 12 is 0, normal I/O is performed under the following conditions: 

1. The monitor echoes all characters typed. 

2. CTRL/U and RUBOUT perform line deletion and character dele- 
tion, respectively. 

3. A carriage return, line feed, CTRL/Z, or CTRL/C must be struck 
before characters on the current line are available to the pro- 
gram. When one of these is typed, characters on the line typed are 
passed one by one to the user program. 

If the console is in special mode (bit 12 set to 1), the following conditions 
apply: 

1. The monitor does not echo characters typed except for CTRL/C 
and CTRL/0. 

2. CTRL/U and RUBOUT do not perform special functions. 
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3. Characters are immediately available to the program. 

4. No ALTMODE conversion is done. 

In special mode, the user program must echo the characters desired. How- 
ever, CTRL/C and CTRL/0 are acted on by the monitor in the usual way. 

Bit 12 in the JSW must be set by the user program if special console mode 
is desired. Bit 14 in the JSW must be set if lowercase characters are de- 
sired. These bits are cleared when control returns to RT-11. 

Regardless of the setting of bit 12, when a carriage return is entered, both 
carriage return and line feed characters are passed to the program; if bit 12 
is 0, these characters will be echoed. 

Lowercase conversion is determined by the setting of bit 14. If bit 14 is 0, 
lowercase characters are converted to uppercase before being echoed (if bit 
12 is 0) and passed to a program; if bit 14 is 1, lowercase characters are 
echoed (if bit 12 is 0) and passed as received. Bit 14 is cleared when the 
program terminates. 

NOTE 

To set and/or clear bits in the JSW, do an IPEEK and then an 
IPOKE (see example under IPOKE). In special terminal 
mode (JSW bit 12 set), normal FORTRAN formatted I/O from 
the console is undefined. 

In the FB or XM monitor, CTRL/F and CTRL/B (and CTRL/X in monitors 
with the system job feature) are not affected by the setting of bit 12. The 
monitor always acts on these characters if the SET TT FB command is in 
effect. 

Also under the FB or XM monitor, if a terminal input request is made and 
no character is available, job execution is normally suspended until a char- 
acter is ready. If a program requires execution to continue and ITTINR to 
return a result of less than zero, it must turn on bit 6 of the JSW before the 
ITTINR. Bit 6 is cleared when a program terminates. The results of 
ITTINR must be stored in an INTEGER type variable for the purposes of 
error checking. Once it is known that the call did not have an error return, 
the result can be moved into a LOGICAL* 1 variable or array element. 
Direct placement into a LOGICAL* 1 variable will lead to incorrect results, 
because the negative flag (bit 15 set) is lost in conversion to a LOGICAL*! 
variable. 

Function Results: 

i >0 Character read. 
<0 No character available. 

Example: 

ICHAR=ITTINR( ) ! READ A CHARACTER FROM THE CONSOLE 

IF< ICHAR.LT.O) GOTO 100 ! CHARACTER NOT AUAILABLE 
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3.60 ITTOUR 

The ITTOUR function transfers a character from the user program to the 
console terminal if there is room for the character in the monitor buffer. If 
it is not currently possible to output a character, an error flag is returned. 

Form: i = ITTOUR (char) 

where: 

char is the character to be output, right-justified in the integer 
(can be LOGICAL*! entity if desired) 

If the function result (i) is 1 when execution of the ITTOUR function is 
complete, it indicates that there is no room in the buffer and that no charac- 
ter was output. Under the FB or XM monitor, ITTOUR normally does not 
return a result of 1. Instead, the job is blocked until room is available in the 
output buffer. If a job requires execution to continue and a result of 1 to be 
returned, it must turn on bit 6 of the JSW (location 44) before issuing the 
request. 

NOTE 

If a foreground job has characters in the TT output buffer, 
they are not output under the following conditions: 

1. If a background job is doing output to the console TT, the 
foreground job cannot output characters from its buffer 
until the background job outputs a line feed character. 
This can be troublesome if the console device is a graph- 
ics terminal and the background job is doing graphic out- 
put without sending any line feeds. 

2. If no background job is running (that is, KMON is in 
control of background), the foreground job cannot output 
its characters until the user types a carriage return or a 
line feed. In the former case, KMON gets control again 
and locks out foreground output as soon as the fore- 
ground output buffer is empty. 

Note that the use of PRINT eliminates these problems. 
Function Results: 



= Character was output. 
= 1 Ring buffer is full. 



Example: 

DO 20 1 = 1 .5 
10 IF(ITTDUR("007) ,NE.O) GOTO 10 IRING BELL 5 TIMES 
20 CONTINUE 

3.61 ITWAIT (SYSGEN Option in SJ) 

The ITWAIT function suspends the main program execution of the current 
job for a specified time interval. All completion routines continue to exe- 
cute. 



System Subroutine Description and Examples 3-59 



Form: i = ITWAIT (itime) 
where: 

itime is the two-word internal format time interval 

itime (1) is the high-order time 
itime (2) is the low-order time 

Notes: 

1. WAIT requires a queue element, which should be considered when the 
IQSET function (Section 3.42) is executed. 

2. If the system is busy, the actual time interval during which execution is 
suspended may be longer than the time interval specified. 

Errors: 

i = Normal return. 
= 1 No queue element available. 

Example: 

INTEGER*2 TIME(2) 

CALL ITWAITdlME) IWAIT FOR TIME 

3.62 lUNTIL (SYSGEN Option in SJ) 

The lUNTIL function suspends main program execution of the job until the 
time of day specified. All completion routines continue to run. 

Form: i := lUNTIL (hrs,min,sec,tick) 
where: 

hrs is the integer number of hours 

min is the integer number of minutes 

sec is the integer number of seconds 

tick is the integer number of ticks (1/60 of a second on 60-cycle 
clocks; 1/50 of a second on 50-cycle clocks) 

Notes: 

1. lUNTIL requires a queue element, which should be considered when 
the IQSET function (Section 3.39) is executed. 

2. If the system is busy, the actual time of day that the program resumes 
execution may be later than that requested. 



Errors: 



i = Normal return. 

= 1 No queue element available. 
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Example: 



TAKE A LUNCH BREAK 

CALL IUNTIL( 13 tO(0 tO) ISTART UP AGAIN AT 1 P.M. 



3.63 IVERIF 

See SYSLIB subroutine VERIFY, Section 3.113. 

3.64 IWAIT 



The IWAIT function suspends execution of the main program until all 
input/output operations on the specified channel are complete. This func- 
tion is used with IREAD, IWRITE, and ISPFN calls. Completion routines 
continue to execute. 

Form: i = IWAIT (chan) 

where: 

chan is the integer specification for the RT-11 channel to be used. 
You must obtain this channel through an IGETC call, or you 
can use channel 16(decimal) or higher if you have done an 
ICDFN call 

For further information on suspending execution of the main program, see 
the .WAIT programmed request (Section 2.96). 

Errors: 

i = Normal return. 
- 1 Channel specified is not open. 

= 2 Hardware error occurred during the previous I/O operation 
on this channel. 

Example: 

IF(IWAIT( ICHAN) .NE.O) CALL I0ERR(4) 

3.65 IWRITE/IWRITC/IWRITF/IWRITW 

The functions IWRITE, IWRITC, IWRITF, and IWRITW transfer a speci- 
fied number of words from memory to the specified channel. The IWRITE 
functions require queue elements; this should be considered when the 
IQSET function (Section 3.42) is executed. 

IWRITE 

The IWRITE function transfers a specified number of words from memory 
to the specified channel. Control returns to the user program immediately 
after the request is queued. No special action is taken upon completion of 
the operation. 

Form: i = IWRITE (wcnt,buff,blk,chan) 
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where: 



went is the integer number of words to be transferred 

buff is the array to be used as the output buffer 

blk is the integer block number of the file to be written. The user 
program normally updates hlk before it is used again 

chan is the integer specification for the RT-11 channel to be used. 
You must obtain this channel through an IGETC call, or you 
can use channel 16(decimal) or higher if you have done an 
ICDFN call 



Errors: 

i = n Normal return; n equals the number of words written, 
rounded to a multiple of 256 (0 for non-file-structured 
writes). 

NOTE 

If the word count returned is less than that re- 
quested, an implied end-of-file has occurred al- 
though the normal return is indicated. 

= -1 Attempt to write past end-of-file; no more space is available 

in the file. 
= -2 Hardware error occurred. 
= -3 Channel specified is not open. 

Example: 

Refer to the example for IREAD. 

IWRITC 

The IWRITC function transfers a specified number of words from memory 
to the specified channel. The request is queued and control returns to the 
user program. When the transfer is complete, the specified assembly lan- 
guage routine {cHn) is entered as an asynchronous completion routine. 

Form: i - IWRITC (wcnt,buff,blk,chan,crtn) 

where: 

went is the relative integer number of words to be transferred 



buff 
blk 



chan 



is the array to be used as the output buffer 

is the relative integer block number of the file to be written. 
The user program normally updates hlk before it is used 
again (for example, if the program is writing two blocks at a 
time, blk should be updated by 2) 

is the relative integer specification for the RT-11 channel to 
be used. You must obtain this channel through an IGETC 
call, or you can use channel 16(decimal) or higher if you have 
done an ICDFN call 
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crtn is the name of the assembly language routine to be activated 
upon completion of the transfer. This name must be specified 
in an EXTERNAL statement in the FORTRAN routine that 
issues the IWRITC call 

Errors: 

See the errors under I WRITE. 

Example: 

INTEGER#2 IBUF(25B) 
EXTERNAL CRTN 



IC0DE=IWRITC(25B >IBUF tIBLK , I CHAN ,CRTN) 

IWRITF 

The IWRITF function transfers a number of words from memory to the 
specified channel. The transfer request is queued and control returns to the 
user program. When the operation is complete, the specified FORTRAN 
subprogram (crtn) is entered as an asynchronous completion routine (see 
Section 1.2.1.2). 

Form: i = IWRITF (wcnt,buff,blk,chan,area,crtnn) 

where: 

went is the integer number of words to be transferred 

buff is the array to be used as the output buffer 

blk is the integer block number of the file to be written. The user 
program normally updates blk before it is used again 

chan is the integer specification for the RT-11 channel to be used. 
You must obtain this channel through an IGETC call, or you 
can use channel 16(decimal) or higher if you have done an 
ICDFN call 

area is a four-word area to be set aside for link information; this 
area must not be modified by the FORTRAN program, and 
the USR must not swap over it. This area can be reclaimed by 
other FORTRAN completion functions when crtn has been 
activated 

crtn is the name of the FORTRAN routine to be activated upon 
completion of the transfer. This name must be specified in an 
EXTERNAL statement in the FORTRAN routine that issues 
the IWRITF call (Section 1.2.1.2 describes completion 
routines) 



Errors: 

See the errors under IWRITE. 
Example: 

Refer to the example under IREADF, Section 3.45. 
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IWRITW 

The IWRITW function transfers a specified number of words from memory 
to the specified channel. Control returns to the user program when the 
transfer is complete. 

Form: i = IWRITW (wcnt,buff,blk,chan) 

where: 

went is the integer number of words to be transferred 
buff is the array to be used as the output buffer 

blk is the integer block number of the file to be written. The user 
program normally updates blk before it is used again 

chan is the integer specification for the RT-11 channel to be used. 
You must obtain this channel through an IGETC call, or you 
can use channel 16(decimal) or higher if you have done an 
ICDFN call 

Errors: 

See the errors under I WRITE. 
Example: 

Refer to the example under IREADW, Section 3.45. 

3.66 JADD 

The JADD function computes the sum of two INTEGER*4 values. 

Form: i = JADD (joprl.jopr2,jres) 

where: 

joprl is an INTEGER*4 variable 

jopr2 is an INTEGER*4 variable 

jres is an INTEGER*4 variable that receives the sum oi joprl and 
jopr2 

Function Results: 

i = -1 Normal return; the result is negative. 
= Normal return; the result is zero. 

= 1 Normal return; the result is positive. 

Errors: 

i = -2 An overflow occurred while computing the result. 

Example: 

INTEGER#il JOPl ,J0P2 ,JRES 

t 
t 
» 

IF( JADD( JDPl tJ0P2 .JRES) ,EC).-2) GOTO 100 
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3.67 JAFIX 

The JAFIX function converts a REAL*4 value to INTEGER*4. 

Form: i = JAFIX (asrcjres) 

where: 

asrc is a REAL*4 variable, constant, or expression to be converted 
to INTEGER*;* 

jres is an INTEGER*4 variable that is to contain the result of the 
conversion 

Function Results: 

i = -1 Normal return; the result is negative. 
= Normal return; the result is zero. 
= 1 Normal return; the result is positive. 

Errors: 

i = -2 An overflow occurred while computing the result. 

Example: 

INTEGER*4 JOPl 
C READ A LARGE INTEGER FROM THE TERMINAL 

ACCEPT 99. A 
99 FORMAT (F15.0) 

IF(JAFIX<A.J0P1) .E0.-2) GOTO 100 



3.68 JCMP 



The JCMP function compares two INTEGER*4 values and returns an IN- 
TEGER*2 value that reflects the signed comparison result. 

Form: i = JCMP (joprl,jopr2) 

where: 

joprl is the INTEGER*4 variable or array element that is the first 
operand in the comparison 

jopr2 is the INTEGER*4 variable or array element that is the sec- 
ond operand in the comparison 

Function Results: 

i = -1 If joprl is less than jopr2. 
= If joprl is equal to jopr2. 
= 1 If joprl is greater than jopr2. 

Errors: 

None. 
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Example: 

INTEGER*4 JOPX , JOPY 

4 
« 

« 

IF(JCMP( JOPX , JOPY) ) 10.20.30 

3.69 JDFIX 

The JDFIX function converts a REAL*8 (DOUBLE PRECISION) value to 
INTEGER*4. 

Form: i = JDFIX (dsrcjres) 

where: 

dsrc is a REAL*8 variable, constant, or expression to be converted 
to INTEGER*4 

jres is an INTEGER*4 variable to contain the conversion result 
Function Results: 

i = -1 Normal return; the result is negative. 
= Normal return; the result is zero. 
= 1 Normal return; the result is positive. 

Errors: 

i = -2 An overflow occurred while computing the result. 
Example: 

INTEGER*^ JNUM 
REAL*S DPNUM 



20 TYPE 98 

38 FORMAK' ENTER POSITIVE INTEGER') 

ACCEPT 93 .DPNUM 
99 F0RMAT(F20.0) 

IF( JDFIXCDPNNUM .JNUM) .LT.O) GOTO 20 



3.70 JDIV 



The JDIV function computes the quotient of two INTEGER*4 values. 

Form: i = JDIV (joprl,jopr2,jres[,jrem]) 

where: 

joprl is an INTEGER*4 variable that is the dividend of the opera- 
tion 
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jopr2 is an INTEGER*4 variable that is the divisor of joprl 

jres is an INTEGER*4 variable that receives the quotient of the 
operation (that is, jres —joprl /jopr2) 

jrem is an INTEGER*4 variable that receives the remainder of the 
operation. The sign is the same as that for joprl 

Function Results: 

i = -1 Normal return; the quotient is negative. 
= Normal return; the quotient is 0. 
= 1 Normal return; the quotient is positive. 

Errors: 

i = -3 An attempt was made to divide by 0. 

Example: 

INTEGER*^ JN1.JN2#J0U0 



CALL JDiyf JNl »JN2 jJQUO) 



3.71 JICVT 



The JICVT function converts a specified INTEGER*2 value to INTE- 
GER*4. 

Form: i = JICVT (isrcjres) 

where: 

isrc is the INTEGER*2 quantity to be converted 

jres is the INTEGER*4 variable or array element to receive the 
result 

Function Results: 

i = — 1 Normal return; the result is negative. 
= Normal return; the result is 0. 
= 1 Normal return; the result is positive. 

Errors: 

None. 

Example: 

INTEGER*^ JMAL 

CALL JICMT<a78»jyAL> ! FORM A 32-BIT CONSTANT 
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3.72 JJCVT 



The JJCVT function interchanges words of an INTEGER*4 value to form 
an internal format time or vice versa. This procedure is necessary when the 
INTEGER*4 variable is to be used as an argument in a timer-support func- 
tion such as ITWAIT. When a two- word internal format time is specified to 
a function such as ITWAIT, it must have the high-order time as the first 
word and the low-order time as the second word. 

Form: CALL JJCVT (jsrc) 

where: 

jsrc is the INTEGER*4 variable whose contents are to be inter- 
changed 

Errors: 

None. 

Example: 

INTEGER*^ TIME 



CALL GTIM(TIME) ! GET TIME OF DAY 

CALL JJCVT(TIME) ! TURN IT INTO INTEGER*^ FORMAT 



3.73 JMOV 



The JMOV function assigns the value of an INTEGER*4 variable to an- 
other INTEGER*4 variable and returns the sign of the value moved. 

Form: i = JMOV (jsrcjdest) 

where: 

jsrc is the INTEGER*4 variable whose contents are to be moved 

jdest is the INTEGER*4 variable that is the target of the assign- 
ment 

Function Results: 

The value of the function is an INTEGER*2 value that represents the sign 
of the result as follows: 

i = -1 Normal return; the result is negative. 
= Normal return; the result is 0. 
= 1 Normal return; the result is positive. 

Errors: 

None. 

Example: 

The JMOV function allows an INTEGER*4 quantity to be compared 
with by using it in a logical IF statement. For example: 
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INTEGER*^ INTl 

* 

IF(JMDU( INTl tlNTl ) .NE.O) GOTO 300 ! GO TO STMT 300 IF INTl NOT 

3.74 JMUL 

The JMUL function computes the product of two INTEGER*4 values. 

Form: i = JMUL (joprlJopr2jres) 

where: 

joprl is an INTEGER*4 variable that is the multiplicand 

jopr2 is an INTEGER*4 variable that is the multiplier 

jres is an INTEGER*4 variable that receives the product of the 
operation 

Function Results: 

i = -1 Normal return; the product is negative. 
- Normal return; the product is 0. 
= 1 Normal return; the product is positive. 

Errors: 

i = -2 An overflow occurred while computing the result. 

Example: 

INTEGER*^ Jl .J2 tJRES 



IF( JMUL( Jl tJ2 »JRES) + 1 ) 100 »10 t20 
C GOTO 100 IF OyERFLOW 
C GOTO 10 IF RESULT IS NEGATIVE 
C GOTO 20 IF RESULT IS POSITIME OR ZERO 



3.75 JSUB 



The JSUB function computes the difference between two INTEGER*4 
values. 

Form: i = JSUB (joprl, jopr2,jres) 

where: 

joprl is an INTEGER*4 variable that is the minuend of the opera- 
tion 

jopr2 is an INTEGER*4 variable that is the subtrahend of the op- 
eration 

jres is an INTEGER*4 variable that is to receive the difference 
between jopri andjpprS (that is, jres = joprl— jopr2) 
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Function Results: 

i = -1 Normal return; the result is negative. 
= Normal return; the result is 0. 
= 1 Normal return; the result is positive. 

Errors: 

i = —2 An overflow occurred while computing the result. 

Example: 

INTEGER*^ J0P1,J0P2.J3 

4 
4 
4 

CALL JSUB( JOPl .J0P2 »J3) 

3.76 JTIME 

The JTIME subroutine converts the time specified to the internal two-word 
format time. 

Form: CALL JTIME (hrs,min,sec,tick,time) 

where: 

hrs is the integer number of hours 

min is the integer number of minutes 

sec is the integer number of seconds 

tick is the integer number of ticks (1/60 of a second for 60-cycle 
clocks; 1/50 of a second for 50-cycle clocks) 

time is the two-word area to receive the internal format time: 
timed) is the high-order time; time(2) is the low-order time 

Errors: 

None. 

Example: 

INTEGER»4 Jl 



CONVERT 3 HRS t 7 MINt 23 SECONDS TO INTEGER *a VALUE 
CALL JTIME(3.7.23 tO .Jl ) 
CALL JJCVTCJl) 



3.77 LEN 



The LEN function returns the number of characters currently in the string 
contained in a specified array. This number is computed as the number of 
characters preceding the first null byte encountered. If the specified array 
contains a null string, a value of is returned. 
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Form: i = LEN (a) 
where: 

a specifies the array containing the string, which must be termi- 
nated by a null byte 

Errors: 

None. 

Example: 

LOGICAL*! STRNG(73) 



TYPE 99 »(gTRNG( I) »I = 1 .LEN(STRNG) ) 
99 FDRMAK '0' »13ZA1) 



3.78 LOCK 



The LOCK subroutine keeps the USR in memory for a series of operations 
involving various RT-11 file management functions. 

If all the conditions that cause swapping are satisfied, a portion of the user 
program is written out to the disk file SWAP.SYS and the USR is loaded. 
Otherwise, the USR in memory is used, and no swapping occurs. The USR 
is not released until an UNLOCK (see Section 3.112) is given. (Note that in 
an FB system, calling the CSI can also perform an implicit UNLOCK.) To 
save time in swapping, a program that has many USR requests to make 
can LOCK the USR in memory, make all the requests, and then UNLOCK 
the USR. 

In an FB or XM environment, a LOCK inhibits another job from using the 
USR. Thus, the USR should be locked only for as long as necessary. 

NOTE 

If any job does a LOCK, it can cause the USR to be unavaila- 
ble for other jobs for a considerable period of time. The USR 
is not reentrant and only one job has use of the USR at a 
time, which should be considered for systems requiring con- 
current foreground and background jobs. This is particularly 
true when magtape and/or cassette are active. 

File operations by the USR require a sequential search of the 
tape for magtape and cassette. This could lock out the fore- 
ground job for a long time while the background job does a 
tape operation. The programmer should keep this in mind 
when designing such systems. The FB and XM monitors sup- 
ply the ITLOCK routine, which permits the foreground job to 
check for the availability of the USR. 

Form: CALL LOCK 
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After a LOCK has been executed, the UNLOCK routine must be executed 
to release the USR from memory. The LOCK/UNLOCK routines are com- 
plementary and must be matched. That is, if three LOCKs are issued, at 
least three UNLOCKS must be done, otherwise the USR is not released. 
More UNLOCKS than LOCKs can occur without error; the extra UN- 
LOCKS are ignored. 

Notes: 

1. It is vital that the LOCK call not come from within the area into which 
the USR will be swapped. If this should occur, the return from the USR 
request would not be to the user program, but to the USR itself, since 
the LOCK function causes part of the user program to be saved on disk 
and replaced in memory by the USR. Furthermore, subroutines, varia- 
bles, and arrays in the area where the USR is swapping should not be 
referenced while the USR is locked in memory. 

2. Once a LOCK has been performed, it is not advisable for the program to 
destroy the area the USR is in, even though no further use of the USR 
is required. This causes unpredictable results when an UNLOCK is 
done. 

3. LOCK cannot be called from a completion or interrupt routine. 

4. If a SET USR NOSWAP command has been issued, LOCK and UN- 
LOCK do not cause the USR to swap. However, in FB, LOCK still 
inhibits the other job from using the USR, and UNLOCK allows the 
other job access to the USR. 

5. The USR cannot accept argument lists, such as device file name specifi- 
cations, located in the area into which it has been locked. 

Errors: 

None. 
Example: 

INTEGER*2 DBLK(4> 

DATA DBLK /3RDK .3RDT ,3RF I L »3RF4 / 



CALL LOCK ILOCK THE USR IN MEMORY 

ICHN=GETC() !GET A CHANNEL TO USE 

IF(LOOKUP( ICHN (DBLK) .LT.O) STOP '7L0DKUP FAILED 
CALL UNLOCK IRELEASE THE USR 



3.79 LOOKUP 

The LOOKUP function associates a specified channel with a device and/or 
file for the purpose of performing I/O operations. The channel used is then 
busy until one of the following functions is executed. 

CLOSEC or ICLOSE 

ISAVES 

PURGE 
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Form: i = LOOKUP (chan,dblk[,count,seqnum,]) 
i - LOOKUP (chanjobdes) 



where: 



chan is the integer specification for the RT-11 channel to be 

associated with the file. You must obtain this channel 
through an IGETC call, or you can use channel 16(deci- 
mal) or higher if you have done an ICDFN call 

dblk is the four-word area specifying the Radix-50 file descrip- 

tor. Note that unpredictable results occur if the USR 
swaps over this four-word area 

ccount is an optional argument used for the cassette handler; this 
argument defaults to 

seqnum is a file number. For cassette operations, if this argument 
is blank, a value of is assumed 

For magtape, it describes a file sequence number. The ac- 
tion taken depends on whether the file name is given or 
null. The sequence number can have the following values: 

-1 Suppress rewind and search for the specified file 
name from the current tape position. If a file name is 
given, a file-structured lookup is performed (do not 
rewind). If the file name is null, a non-file-structured 
lookup is done (tape is not moved). You must specify 
a -1 and no other negative number. 

Rewind to the beginning of the tape and do a non- 
file-structured lookup. 

n Where n is any positive number. Position the tape at 
file sequence number n and check that the file 
names match. If the file names do not match, an er- 
ror is generated. If the file name is null, a file-struc- 
tured lookup is done on the file designated by seq- 
num. 

jobdes is an argument that allows communication between jobs 
in a system job environment. It is a pointer to a four-word 
job descriptor of the job to which messages will be sent or 
received. The syntax is 

jobdes -^ .RAD50 /MQ/ 

.ASCII /logical-job-name/ 

where the logical-job -name is six characters long. If the 
logical-job-name is zero, the channel will be opened only 
for .READ/CAV requests, and such requests will accept 
messages from any jobs. 

If the jobdes argument is omitted, .LOOKUP operates as it 
did for Version 3B. 
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NOTE 

The arguments of LOOKUP must be positioned so that the 
USR does not swap over them. 

The handler for the selected device must be in memory for a LOOKUP. If 
the first word of the file name in dblk is and the device is a file-structured 
device, absolute block of the device is designated as the beginning of the 
file. This technique, called a non-file-structured lookup, allows I/O to any 
physical block on the device. If a file name is specified for a device that is 
not file structured (such as LP:FILE.TYP), the name is ignored. 

NOTE 

Since a non-file-structured lookup allows I/O to any physical 
block on the device, the user must be aware that, in this 
mode, it is possible to overwrite the RT-11 device directory, 
thus destroying all file information on the device. 

Function Results: 

i = n Indicates a successful file-structured lookup on a random- 
access storage volume. 

i = Indicates a successful non-file-structured lookup on both 
random-access and non-file-structured volumes, or a suc- 
cessful file-structured lookup on magtape. 



Errors: 



1 = 



-1 Channel specified is already open. 

-2 File specified was not found on the device. 

—3 Device in use. 

-4 Tape drive is not available. 

-5 Illegal argument error with a file-structured volume. 

-6 Illegal argument error with a non-file-structured volume. 



Example: 



INTEGER*2 DBLK(4) 

DATA DBLK/3RDK0,3RFTN »3Ra4 



tSRDAT/ 



ICHAN=IGETC( ) 

IF(ICHAN.LT.O) STOP 'NO CHANNEL' 
IF(IFETCH(DBLK) .NE.O) STOP 'BAD FETCH' 
IF(LOOKUP(ICHAN tDBLK) .LT.O) STOP 'BAD LOOKUP- 



CALL ICLOBEf ICHAN tl) 

I = ICLOSE() 

CALL IFREEC( ICHAN) 
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or using LOOKUP with a system job 

LOGICAL*! JNAM(B) 
DIMENSION JBLK(a) 
EOUIUALENCE ( JNAM (1 ) . JBLK ( Z ) ) 
DATA JNAM / '0 ' * 'U ' , ' E ' » 'U ' t 'E ' »0/ 
DATA JBLK( 1 ) /3RM0 / 



OPEN A MESSAGE CHANNEL TO 'QUEUE' 

ICHN = GETC( ) 

IF(LOOKUP(ICHN»JBLK) .LT.O) STOP 'QUEUE IB NOT RUNNING' 



3.80 MRKT (SYSGEN Option in SJ) 

The MRKT function schedules an assembly language completion routine to 
be entered after a specified time interval has elapsed. Support for MRKT in 
SJ requires timer support. 

Form: i = MRKT (id,crtn,time) 

where: 

id is an integer identification number to be passed to the routine 

being scheduled 

crtn is the name of the assembly language routine to be entered 
when the time interval elapses. This name must be specified 
in an EXTERNAL statement in the FORTRAN routine that 
issues the MRKT call 

time is the two- word, internal format time interval; when this in- 
terval elapses, the routine is entered. If considered as a two- 
element INTEGER*2 array: 

time(l) is the high-order time. 
time(2) is the low-order time. 

Notes: 

1. MRKT requires a queue element, which should be considered when the 
IQSET function (Section 3.42) is executed. 

2. If the system is busy, the time interval that elapses before the comple- 
tion routine is run can be greater than that requested. 

For further information on scheduling completion routines, see the .MRKT 
programmed request (Section 2.45). 



Errors: 



i = Normal return. 
= 1 No queue element was available; unable to schedule re- 
quest. 
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Example: 



INTEGER*2 TINT(2) 
EXTERNAL ARTN 



CALL MRKT(4 , ARTN .TINT) 



3.81 MTATCH (Special Feature) 

The MTATCH subroutine attaches a terminal for exclusive use by the re- 
questing job. This operation must be performed before any job can use a 
terminal with multi terminal programmed requests. 



Form: 
where: 



MTATCH (unit[,addr][,jobnum]) 



unit is the logical unit number (lun) of the terminal 

addr is the optional address of an asynchronous terminal status 

word. Omit this argument if the asynchronous terminal 
status word is not required by specifying a comma. For 
example: 



jobnum 



Errors: 



i = 
= 3 
= 5 



I = MTATCH (unit„jobnum) 

is the job number associated with the terminal if the ter- 
minal is not available 



Normal return. 
Nonexistent unit number. 

Unit attached by another job (job number returned in job- 
num) 

In XM monitor, the optional status word address is not in a 
valid user virtual address space 



Example: 



TEST SYBLIB MULTI TERMI NAL ROUTINES 

INTEGER*2 UNIT .SBLOK ( ^ > iSTAT(8) iftSW iSTRI NG ( fll ) iPROMT(B) 

LOGICAL*! TEND(ll) 

REAL*il TESTMO) 

DATA PROMT/ 'EN' f 'TE' . 'R ' . 'ST ' > ' RI ' . ' NG ' . ' > ' i "200/ 

DATA TEND/ '♦' < 'E ' t 'N' ( 'D' t ' ' » ' T ' . 'E ' i 'S ' i 'T ' . ' » ' .0/ 

DATA TESTM/ 'STAT' . 'ATCH' . 'GET' . 'SET '.''.''»''.'' . 'DTCH'/ 

USE MTSTAT TO GET 8. DISPLAY NO. OF UNITS 



TYPE lOG 

L=l 

IF(I1TSTAT(STAT) .NE.O)GOTO 999 

TYPE 93.STAT(3) 

GET UNIT * TO TEST 



ANNOUNCE TEST 
L = FUNC CODE 
GET MTTY STATUS 
DISPLAY « UNITS 
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TYPE 100 ! TYPE PROMPT 

ACCEPT 101 (UNIT ! GET UNIT « 

IF(UNIT.E0.99) STOP 'END OF MULT ITERMI NAL TEST'! UNIT »33 STOPS TEST 

ATTACH UNIT TO THIS JOB THEN GET TCB STATUS NORDS 



TYPE 110 

ACCEPT 111 .lASW 

IF( lASW.EQ, 'Y' ) IER = MTATCH(UNITtASW .JOB) 

IF( lASW.NE. 'Y' ) IER = MTATCH(UNIT .0 tJOB) 

L = 2 

IF<IER)GOTO 999 

L = 3 

IF(MTGET(UNIT ,SBLOK( 1 ) ) .NE.O)GOTO 999 

TYPE 102 fUNIT tSBLOK 



SEE IF ASW TEST 
IS TO BE DONE 
ATT W/ ASW IF YES 
ATT W/0 ASW IF NO 

! REPORT ERROR IF ANY 

! GET TCB WORDS 

! DISPLAY CONTENTS 



GET NEW STATUS, PUT IT IN TCB. THEN DISPLAY IT 



CALL SETUP(SBLOK.UNIT) 

L = 4 

IF(MTSET(UNIT ,SBLQK( 1 ) ) .NE.OJGOTO 999 

TYPE 102 .UNIT, SBLOK 



! GET CHANGES IF ANY 

! GET NEW TCB STATUS 
! THEN DISPLAY IT. . . 



C 
20 

30 



PERFORM TEST 



FIRST ECHO INPUT THEN REPEAT IT USING MTIN & MTDUT 



TYPE 103 

TYPE 104 

TYPE 105 

CALL MTIN(UNIT,J) 

CALL MTOUT(UNIT ,J) 

IF( J.NE.IOJGOTO 30 

CALL MTRCTO(UNIT) 



! ANNOUNCE RULES OF 

! THE TEST. . . 

GET LINE OF INPUT 
REPEAT IST/ECHO 2ND 
LF = END OF LINE 
RESET CTRL/0 



C NOW TEST W/ TTSPC$ BIT ON 
C THEN TURN TTSPC* BIT OFF,. 



ECHO INPUT WITH MTOUT (DON'T REPEAT) 



ao 



IF(SBLOK( 1 ) .AND. "10000)G0T0 UO 
SBLOK ( 1 )= SBLOK ( 1 ) .OR. "10000 
IF(MTSET(UNIT .SBLOK ( 1 ) ) . NE . ) GOTO 999 
GOTO 30 

SBLOK ( 1 )= SBLOK ( 1 ) .AND. .NOT. "10000 
IF<MTSET(UNIT , SBLOK ( 1 ) ) .NE.O)GOTO 339 

IF( iasw.ne. 'Y' )goto go 



IF TTSPC* ON BRANCH 

set TTSPC* BIT 

UPDATE TCB 

GO DO 2ND TEST 

TURN OFF TTSPC* BIT 

UPDATE TCB 

SKIP ASW TEST? 



ASYNCHRONOUS STATUS WORD TEST - "POLL" TERMINAL UNTIL INPUT 
AVAILABLE - ECHO INPUT THEN REPEAT IT ON NEXT LINE 



TYPE 109 
50 IF ( .NOT. ASW. AND, "40000) GOTO 50 
55 CALL MTIN(UNIT,J) 

CALL MTOUT(UNIT ,J) 

IF(J.NE,10)G0T0 55 

CALL MTRCTO(UNIT) 



ANNOUNCE TEST 
WAIT FOR INPUT 
GET CHAR 
OUTPUT CHAR 
END ON LINE FEED 
RESET CTRL/0 



C 
60 



TEST MTPRNT BY OUTPUTTING 2 STRINGS, 1 FROM USER & 1 INTERNAL 



CALL GTLIN(STRING, PROMT) 
CALL MTPRNT(UNIT, STRING) 
CALL MTPRNT(UNIT,TEND) 



GET STRING MIA GTLIN 
OUTPUT TO TERMINAL 
ANNOUNCE END OF TEST 



DETACH UNIT FROM JOB AND START OMER 



L = 9 

TYPE 108, UNIT 

IF(MTDTCH(UNIT) .EO.O)GOTO 5 



! DETATCH UNIT 

! FROM JOB THEN LOOP 
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c 


ERROR REPORTING 


999 


TYPE 909.TESTM(L) ,IER ! ANNOUNCE ERROR 




GOTO 5 ! THEN START OVER 


93 


FDRMflTf 'OTHERE ARE'. 13,' UNITS ON THIS SYSTEM') 


100 


FORMAT( '*UNIT « TO BE TESTED?') 


101 


FORMATf 12) 


102 


FORMAT( 'OUNIT' .13.' STATUS ='.4D8) 


103 


FORMATC'O-GO TO TERMINAL BEING TESTED ... ENTER 2 LINES + (Effl ' ) 


loa 


FORMAT(' 1ST LINE: INPUT WILL BE ECHOED THEN REPEATED') 


105 


FORMAT(' 2ND LINE: TEST TTSPC$ ON - INPUT ECHOED VIA MTOUT'/) 


lOB 


FORMAT('l SYSLIB MULT ITERM I NAL ROUTINE TEST PROGRAM') 


108 


FQRMAT(' ABOUT TODETACH UNIT « ',12) 


109 


FORMAT(' TEST ASH - INPUT WILL BE ECHOED. THEN REPEATED'/) 


110 


FORMAT( '*TEST ASYNCH STATUS WORD FUNCTION?') 


1 11 


F0RMAT(A1 ) 


909 


FORMAT( 'OMT' .A4. ' ERROR CODE ='.I3) 




END 



SUBROUTINE TO GET NEW STATUS WORD VALUES 
SUBROUTINE SETUP ( SBLOK .UN I T ) 



INTEGER SBLOK(a) .UNIT 





TYPE 100 




ACCEPT 101 .J 




IF(J)SBL0K(1 )=J 




TYPE 102 




ACCEPT 101 .J 




TYPE 103 




ACCEPT 101 .1 




IF (I .DR. J)SBL0K(3)=I»25B+J 


5 


TYPE 104 




ACCEPT 105.1 




IF(I)BBLDK(4)=SBL0K(4)/25S*256+I 




RETURN 


100 


FORMAT( 'SCONFIG BIT MASK:') 


101 


FORMAT(OB) 


102 


FORMAT( '$CHAR REQUIRING FILLER:') 


103 


FORMAT('$» OF FILL CHARS:') 


104 


FORMAT( '*CARRIAGE WIDTH:') 


105 


F0RMAT(I3) 




END 



PROMPT FOR NEW CONFIG WORD 

ACCEPT INPUT 

UPDATE IF ANY INPUT 

ASK FOR FILL CHAR 

ACCEPT IT 

ASK FOR tt OF FILL CHARS 

ACCEPT IT TOO 

PUT IN PROPER BYTES 

ASK FOR CARRIAGE WIDTH 

ACCEPT IT 

SET BUT DON'T MESS WITH 

STATE WORD . . . RETURN 



3.82 MTDTCH (Special Feature) 

The MTDTCH subroutine is the complement of the MTATCH subroutine. 
Its function is to detach a terminal from a particular job and make it avail- 
able for other jobs. 

Form: i = MTDTCH(unit) 

where: 

unit is the logical unit number (lun) of the terminal to be detached 

Errors: 

i = Normal return. 
= 2 Invalid unit number; terminal is not attached. 
= 3 Nonexistent unit number. 
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Example: 

Refer to the example under MTATCH. 



3.83 MTGET (Special Feature) 



The MTGET subroutine furnishes the user with information about a spe- 
cific terminal in a multiterminal system. You do not need to do an 
MTATCH before using MTGET. 

Form: i = MTGET (unit,addr[,jobnum]) 

where: 

unit is the unit number of the line and terminal whose status is 

desired 

addr is the four-word area to receive the status information. The 

area is a four-element INTEGER*2 array (see the .MTSET 
programmed request, Section 2.54, for area format) 

jobnum is the job number associated with the terminal if the termi- 
nal is not available 

Status information including bit definitions for the terminal configuration 
words and the terminal state byte are described in detail under the 
.MTGET programmed request. 

Errors: 

i = Normal return. 

= 2 Unit not attached. 

= 3 Nonexistent unit number. 

= 4 Unit attached by another job (job number returned in job- 
num). 

= 6 In XM monitor, the address of the terminal buffer is outside 
the valid program limits. 

Example: 

Refer to the example under MTATCH. 



3.84 MTIN (Special Feature) 



The MTIN subroutine transfers characters from a specified terminal to the 
user program. This subroutine is a multiterminal form of ITTINR. If no 
characters are available, an error flag is set to indicate an error upon re- 
turn from the subroutine. If no character count argument is specified, one 
character is transferred. 

Form: i = MTIN (unit,char[,chrcnt ][,ocnt]) 

where: 

unit is the unit number of the terminal 

char is the variable to contain the characters read in from the 
terminal indicated by the unit number 
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chrcnt is an optional argument that indicates the number of char- 
acters to be read 

ocnt is an optional argument that indicates the number of char- 

acters actually transferred 

When a request for a multiple-character transfer is requested, if the op- 
tional fourth argument (ocnt) is specified and bit 6 of the M.TSTS word is 
set, the variable specified as the argument will have a value equal to the 
actual number of characters transferred upon return from the subroutine. 

Errors: 

i = Normal return. 

= 1 No input available. 

= 2 Unit not attached. 

= 3 Nonexistent unit number. 

Example: 

Refer to the example under MTATCH. 



3.85 MTOUT (Special Feature) 



The MTOUT subroutine transfers characters to a specified terminal. This 
subroutine is a multiterminal form of ITTOUR. If no room is available in 
the output ring buffer, an error flag is set to indicate an error upon return 
from the subroutine. If no character count argument is specified, one char- 
acter is transferred. 

Form: i = MTOUT (unit,char[,chrcnt][,ocnt]) 

where: 

unit is the unit number of the terminal 

char is the variable or array containing the characters to be out- 
put, right-justified in the! integer (can be LOGICAL*! if de- 
sired) 

chrcnt is an optional argument that indicates the number of char- 
acters to be output 

ocnt is an optional argument that indicates the number of char- 

acters actually transferred 

When a request for a multiple-character transfer is requested, if the op- 
tional fourth argument (ocnt) is specified and bit 6 of the M.TSTS word is 
set, the variable specified as the argument will have a value equal to the 
actual number of characters transferred upon return from the subroutine. 

Errors: 

i = Normal return. 
= 1 No room in output ring buffer. 
= 2 Unit not attached. 
= 3 Nonexistent unit number. 

= 5 In the XM monitor, the address of the user buffer is outside 
the valid program limits. 
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Example: 

Refer to the example under MTATCH. 

3.86 MTPRNT (Special Feature) 

The MTPRNT subroutine allows output to be printed at any terminal in a 
multiterminal environment. This subroutine has the same effect as the 
PRINT subroutine (Section 3.91). 

Form: i = MTPRNT (unit,string) 

where: 

unit is the unnit number associated with the terminal 

string is the character string to be printed. Note that all quoted 
literals used in FORTRAN subroutine calls are in ASCIZ 
format, which ends in zero for a CR/LF or a 200 if no action 
is to be taken 

Errors: 

i = Normal return. 
= 2 Unit not attached. 
= 3 Nonexistent unit number. 

= 5 In the XM monitor, the address of the character string is 
outside the valid program limits. 

3.87 MTRCTO (Special Feature) 

The MTRCTO subroutine resets the CTRL/0 command typed at the speci- 
fied terminal in a multiterminal environment. This subroutine has the 
same effect as the .MTRCTO programmed request (Section 2.53). 

Form: i = MTRCTO(unit) 

where: 

unit is the unit number associated with the terminal 

Errors: 

i = Normal return. 
— 2 Unit not attached. 
= 3 Nonexistent unit number. 

Example: 

Refer to the example under MTATCH. 



3.88 MTSET (Special Feature) 



The MTSET subroutine sets terminal and line characteristics. The set con- 
ditions remain in effect until the system is booted or the terminal and line 
characteristics are reset. See the .MTSET programmed request (Section 
2.54) for more details. 
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Form: i = 
where: 

unit 



addr 



MTSET (unit,addr) 



is the unit number of the line and terminal whose character- 
istics are to be changed 

is a four-word area to pass the status information. The area is 
a four-element INTEGER*2 array 



Errors: 



i = 

= 2 

= 3 

= 6 



Normal return. 

Unit not attached. 

Nonexistent unit number. 

In the XM monitor, the address of the status block is outside 

the valid program limits. 



Example: 



Refer to the example under MTATCH. 

3.89 MTSTAT (Special Feature) 

The MTSTAT subroutine returns multiterminal system status in an eight- 
word status block. 

Form: i = MTSTAT (addr) 

where: 

addr is the address of an eight-word array where multiterminal 
status information is returned. The status block contains the 
following information: 

Contents 

addr(l) Offset from the base of the resident monitor to 

the first Terminal Control Block (TCB). 

addr(2) Offset from the base of the resident monitor to 

the terminal control block of the console termi- 
nal for the program. 

addr(3) The value (0-16 decimal) of the highest logical 

unit number (LUN) built into the system. 

addr (4) The size of the terminal control block in bytes. 

addr(5)-(8) Reserved. 



Errors: 



i = Normal return. 

— 5 In the XM monitor, the address of the status block is not in 
valid user address space. 

Example: 

Refer to the example under MTATCH. 
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3.90 MWAIT (FB and XM Only) 

The MWAIT subroutine suspends main program execution of the current 
job until all messages sent to or from the other job have been transmitted or 
received. It provides a means for ensuring that a required message has 
been processed. MWAIT is used primarily in conjunction with the IRCVD 
and ISDAT calls, where no action is taken when a message transmission is 
completed. This subroutine requires a queue element, which should be con- 
sidered when the IQSET function (Section 3.42) is executed. 

Form: CALL MWAIT 

Errors: 

None. 
Example: 

Refer to the example under ISDAT, Section 3.51. 



3.91 PRINT 



The PRINT subroutine prints output from a specified string at the console 
terminal. This routine can be used to print messages from completion 
routines without using the FORTRAN formatted I/O system. Control re- 
turns to the user program after all characters have been placed in the 
output buffer. 

The string to be printed can be terminated with either a null (0) byte or a 
200(octal) byte. If the null (ASCIZ) format is used, the output is automati- 
cally followed by a carriage return/line feed pair (octal 15 and 12). If a 200 
byte terminates the string, no carriage return/line feed pair is generated. 

In the FB monitor, a change in the job that is controlling terminal output is 
indicated by a B> or F>. Any text following the message has been printed 
by the job indicated (foreground or background) until another B> or F> is 
printed. When PRINT is used by the foreground job, the message appears 
immediately, regardless of the state of the background job. Thus, for urgent 
messages, PRINT should be used rather than ITTOUR. 

Form: CALL PRINT (string) 

where: 

string is the string to be printed. Note that all quoted literals used 
in FORTRAN subroutine calls are in ASCIZ format, as are 
all strings produced by the SYSLIB string-handling package 
(The CONCAT routine can be used to append an octal 200 to 
an ASCIZ string; see example.) 

Errors: 

None. 
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Example: 



CALL PRINT ('THE COFFEE IS READY') 

r 

BYTE 0UESTI0N(80) 

! APPEND BYTE ZOO 

CALL CONCAT('WHAT IS YOUR NAME? . "200 , QUEST ION > 

CALL PRINT(OUESTION) IQUESTION PRINTS WITHOUT CR tLF 



3.92 PURGE 



The PURGE subroutine deactivates a channel without performing an 
ISAVES, CLOSEC, or ICLOSE. Any tentative file currently associated 
with the channel is not made permanent. This subroutine prevents entered 
(lENTER or .ENTER) files from becoming permanent directory entries. 

Form: CALL PURGE (chan) 

where: 

chan is the integer specification for the RT-11 channel to be deac- 
tivated 

Errors: 

None. 
Example: 

Refer to the example under lENTER, Section 3.25. 



3.93 PUTSTR 



The PUTSTR subroutine writes a variable-length character string to a 
specified FORTRAN logical unit. PUTSTR can be used in main program 
routines or in completion routines but not in both in the same program at 
the same time. If PUTSTR is used in a completion routine, it must not be 
the first I/O operation on the specified logical unit. 

Form: CALL PUTSTR (lun,in,char,err) 

where: 

lun is the integer specification of the FORTRAN logical unit 
number to which the string is to be written 

in is the array containing the string to be written 

char is an ASCII character that is appended to the beginning of the 
string before it is output. If 0, no extra character is output. 
This character is used primarily for carriage control purposes 

err is a LOGICAL*! variable that is .TRUE, for an error condi- 
tion and .FALSE, for a no-error condition 



3-84 System Subroutine Description and Examples 



Errors: 

err = -1 End-of-file for write operation. 

-2 Hardware error for write operation. 

Example: 

LOGICAL*! STRNG(Bl) tERR 



mUTPUT STRING WITH DOUBLE SPACING 
CALL PUTSTR<7*STRNG>'0' tERR) 



3.94 R50ASC 



The R50ASC subroutine converts a specified number of Radix-50 charac- 
ters to ASCII, t , 

Form: CALL R50ASC (icnt,input,output) 

where: 

icnt is the integer number of ASCII characters to be produced 

input is the area from which words of Radix-50 values to be con- 
verted are taken. Note that (icre^ + 2)/3 words are read for 
conversion 

output is the area into which the ASCII characters are stored 

Errors: 

If an input word contains illegal Radix-50 codes — that is, if the 
input word is greater (unsigned) than 174777(octal) — the routine 
outputs question marks for the value. 

Example: 

REAL*8 NAME 
LOGICAL*! OUTP(IZ) 



CALL R50ASC(12»NAMEtOUTP) 

3.95 RAD50 

The RAD50 function provides a method of encoding RT-11 file descriptors 
in Radix-50 notation. The RAD50 function converts six ASCII characters 
from the specified area, returning a REAL*4 result that is the two-word 
Radix-50 value. 



Form: a = RAD50 (input) 
where: 

input is the area from which the ASCII input characters are taken 



4 l^^U^ r i^cSr-' 
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The RAD50 call: 

A = RAD50 (LINE) 

is exactly equivalent to the IRAD50 call: 

CALL IRAD50 (GiLINEtA) 

Function Results: 

The two-word Radix-50 value is returned as the function result. 

3.96 RCHAIN 

The RCHAIN subroutine allows a program to determine whether it has 
been chained to and to access variables passed across a chain. If RCHAIN is 
used, it must be used in the first executable FORTRAN statement in a 
program. 

Form: CALL RCHAIN (flag,var,wcnt) 

where: 

flag is an integer variable that RCHAIN will set to -1 (true) if the 
program has been chained to; otherwise, it is (false) 

var is the first variable in a sequence of variables with increasing 
memory addresses to receive the information passed across 
the chain (see Section 3.2) 

went is the number of words to be moved from the chain parameter 
area to the area specified by var. RCHAIN moves went words 
into the area beginning at var 

Errors: 

None. 

Example: 

INTEGER#2 PARMS(50) 

CALL RCHAINdFLAG fPARMS .50) 

IF(IFLAG) GOTO 10 !GOTO 10 IF CHAINED TO 



3.97 RCTRLO 

The RCTRLO subroutine resets the effect of any console terminal CTRL/0 
command that was typed. After an RCTRLO call, any output directed to the 
console terminal prints until another CTRL/0 is typed. 

Form: CALL RCTRLO 

Errors: 

None. 
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Example: 



CALL RCTRLD 

CALL PRINT ('PRINT UNTIL ANOTHER CTRL/Q TYPED') 



3.98 REPEAT 



The REPEAT subroutine concatenates a specified string with itself to pro- 
duce the indicated number of copies. REPEAT places the resulting string in 
a specified array. 

Form: CALL REPEAT (in,out,i[,len[,err]]) 

where: 

in is the array containing the string to be repeated; it must be 
terminated with a null byte 

out is the array into which the resultant string is placed. This 
array must be at least one element longer than the value of 
len, if len is specified. It also must be terminated with a null 
byte if len is specified 

i is the integer number of times to repeat the string 

len is the integer number representing the maximum length of the 
output string 

err is the logical error flag set if the output string is truncated to 
the length specified by len 

Input and output strings can specify the same array only if the repeat count 
(i) is 1 or 0. When the repeat count is 1, this routine is the equivalent of 
SCOPY; when the repeat count is 0, out is replaced by a null string. The old 
contents of out are lost when this routine is called. 

Errors: 

Error conditions are indicated by err, if specified. If err is given and 
the output string would have been longer than len characters, then 
err is set to .TRUE.; otherwise, err is unchanged. 

Example: 

LOGICAL*! SIN<21) .SOUTdOl ) 



CALL REPEAT<SIN»S0UT»5> 

3.99 RESUME (FB and XM Only) 

The RESUME subroutine allows a job to resume execution of the main 
program. A RESUME call is normally issued from an asynchronous FOR- 
TRAN routine entered on I/O completion or because of a schedule request 
(see the SUSPND subroutine. Section 3.107, for more information). 
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Form: CALL RESUME 
Errors: 

None. 
Example: 

Refer to the example under SUSPND. 

3.100 SCCA 

The SCCA subroutine provides a CTRL/C intercept to: 

1. Inhibit a CTRL/C abort 

2. Indicate that a CTRL/C command is active 

3. Distinguish between single and double CTRL/C commands 

Form: CALL SCCA [(iflag)] 
where: 

iflag is an integer terminal status word that must be tested and 
cleared to determine if two CTRL/Cs were typed at the con- 
sole terminal; the iflag must be an INTEGER*2 variable (not 
LOGICAL*!) 

When a CTRL/C is typed, the SCCA subroutine places it in the input ring 
buffer. While residing in the buffer, the character can be read by the pro- 
gram. The program must test and clear the iflag to determine if two 
CTRL/C commands were typed consecutively. The iflag is set to non-zero 
when two CTRL/Cs are typed together. It is the responsibility of the pro- 
gram to abort itself, if appropriate, on an input of CTRL/C from the termi- 
nal. The SCCA subroutine with no argument disables the CTRL/C inter- 
cept. A CTRL/C from indirect command files is not intercepted by SCCA. 

Errors: 

None. 

Example: 

PROGRAM SCCA 
C SCCA. FOR SYSLIB TEST FOR SCCA 
C 

CALL PRINT ('PROGRAM HAS STARTED* TYPE') 

IFLAG=0 

CALL SCCA (IFLAG) 
10 I = ITTINRO !GET A CHARACTER 

IF (I .NE. 3) GOTO 10 
C A CTRL/C WAS TYPED 

CALL PRINT ('A CTRL/C WAS TYPED') 

IF (IFLAG .EO. 0) GOTO 10 

CALL PRINT ('A DOUBLE CTRL/C WAS TYPED') 

TYPE 19»IFLAG 

19 FORMAT ( ' IFLAG = ' ,0G»/) 

CALL SCCA (DISABLE CTRL/C INTERCEPT 

CALL PRINT ('TYPE A CTRL/C TO EXIT') 

20 GOTO 20 ILOOP UNTIL CTRL/C TYPED 
END 
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3.101 SCOMP/ISCOMP 



The SCOMP routine compares two character strings and returns the inte- 
ger result of the comparison. 

Form: CALL SCOMP (a,b,i) 

or 

i = ISCOMP(a,b) 

where: 

a is the array containing the first string; it must be terminated 
with a null byte 

b is the array containing the second string; it must be terminated 
with a null byte 

i is the integer variable that receives the result of the comparison 

The strings are compared from left to right, one character at a time, using 
the collating sequence specified by the ASCII codes for each character. If 
the two strings are not equal, the absolute value of variable i (or the result 
of the function ISCOMP) is the character position of the first inequality 
found. Strings are terminated by a null (0) character. 

If the strings are not the same length, the shorter one is treated as if it 
were padded on the right with blanks to the length of the other string. A 
null string argument is equivalent to a string containing only blanks. 

Function Results: 

i <0 If a is less than b. 
= If a is equal to b. 
>0 If a is greater than b. 

Example: 

LOGICAL*! INSTR(8n 



CALL GETSTR(5»INSTR»80) 

CALL SCOMP( 'YES' flNSTRdMAL) 

IFCIVAL.NE.O) GOTO 10 !IF INPUT STRING IS NOT YES GOTO 10 



3.102 SCOPY 



The SCOPY routine copies a character string from one array to another. 
Copying stops either when a null (0) character is encountered or when a 
specified number of characters have been moved. 

Form: CALL SCOPY (in,out[,len[,err]]) 

where: 

in is the array containing the string to be copied; it must be ter- 
minated with a null byte if len is not specified, or if the string 
is shorter than len 
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out is the array to receive the copied string. This array must be at 
least one element longer than the value of len, if len is speci- 
fied. It also must be terminated with a null byte if len is speci- 
fied 

len is the integer number representing the maximum length of the 
output string. The effect of len is to truncate the output string 
to a given length 

err is a logical variable that receives the error indication if the 
output string was truncated to the length specified by len 

The input (in) and output (out) arguments can specify the same array. The 
string previously contained in the output array is lost when this subroutine 
is called. 



Errors: 



Error conditions are indicated by err, if specified. If err is given and 
the output string was truncated to the length specified by len, then 
err is set to .TRUE.; otherwise, err is unchanged. 



Example: 



SCOPY is useful for initializing strings to a constant value, for exam- 
ple: 



LOGICAL*! STRING(BO) 

CALL SCOPY('THIS IS THE INITIAL VALUE ' »STR I NG ) 



3.103 SECNDS 



The SECNDS function returns the current system time, in seconds past 
midnight, minus the value of a specified argument. Thus, SECNDS can be 
used to calculate elapsed time. The value returned is single-precision float- 
ing point (REAL*4). 

Form: a = SECNDS (atime) 

where: 

atime is a REAL*4 variable, constant, or expression whose value is 
subtracted from the current time of day to form the result 

Notes: 

This function does floating-point arithmetic. Elapsed time can also be cal- 
culated by using the GTIM call and the INTEGER*4 support functions. 

Function Result: 

The function result (a) is the REAL*4 value returned. 

Errors: 

None. 
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Example: 



C START OF TIMED SEQUENCE 

T1=SECNDS(0. ) 
C 

C CODE TO BE TIMED GOES HERE 
C 



DELTA=SECNDS(T1) IDELTA IS ELAPSED TIME 



3.104 SETCMD 



The SETCMD routine allows a user program to pass a command line to the 
keyboard monitor to be executed after the program exits. The command 
lines are passed to the chain information area (500-777 octal) and stored 
beginning at location 512(octal). No check is made to determine if the 
string extends into the stack space. For this reason, the command line 
should be short and the subroutine call should be made in the main pro- 
gram unit near the end of the program just before completion. When sev- 
eral commands are involved, an indirect command file that contains sev- 
eral command lines should be used. 

The monitor commands REENTER, START, and CLOSE are not allowed if 
the SETCMD feature is used. 

Form: CALL SETCMD (string) 

where: 

string is a keyboard monitor command line in ASCIZ format with 
no embedded carriage returns or line feeds 

Errors: 

None. 

Example: 

LOGICAL*! >INPUT( 134) .PROMPT(B) 

DATA PROMPT/ 'P'>'R't'0'f'M'»'P'»'T't'>' ."200/ 

CALL GTLIN (INPUT .PROMPT ) 

CALL SETCMD (INPUT) 

END 

NOTE 

Set USR NOSWAP, or specify /NOSWAP with the COM- 
PILE, FORTRAN, or EXECUTE command to control the 
swapping state of the USR. A LOCK would inhibit another 
job from using the USR. 

A STOP or CALL EXIT must also be issued after the SETCMD to cause an 
exit. 



3.105 STRPAD 



The STRPAD routine pads a character string with rightmost blanks until 
that string is a specified length. This padding is done in place; the result 
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string is contained in its original array. If the present length of the string is 
greater than or equal to the specified length, no padding occurs. 

Form: CALL STRPAD (a,len[,err]) 

where: 

a is the array containing the string to be padded. This array 
must be one element longer than the value of len if len is speci- 
fied. It will be terminated by a null byte 

len is the integer length of the desired result string 

err is the logical error flag that is set to .TRUE, if the string speci- 
fied by a exceeds the value of i in length 



Errors: 



Error conditions are indicated by err, if specified. If err is given and 
the string indicated is longer than i characters, err is set to .TRUE.; 
otherwise, the value of err is unchanged. 



Example: 



This routine is especially useful for preparing strings to be output in 
A-type FORMAT fields. For example: 



LOGICAL*! STR(81) 



CALL STRPAD(STR»80> ! ASSURE 80 VALID CHARACTERS 
PRINT 100>(STR( I) »I=1 tBO) IPRINT STRING OF 80 CHARACTERS 
100 FORMAT(SOAl) 



3.106 SUBSTR 



The SUBSTR routine copies a substring from a specified position in a char- 
acter string. If desired, the substring can then be placed in the same array 
as the string from which it was taken. 

Form: CALL SUBSTR (in,out,i[,len]) 

where: 

in is the array from which the substring is taken; it is terminated 
by a null byte 

out is the array to contain the substring result. This array must be 
one element longer than len, if len is specified. It also is termi- 
nated by a null byte if len is specified 

i is the integer character position in the input string of the first 

character of the desired substring 

len is the integer number of characters representing the maximum 
length of the substring 
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If a maximum length (len) is not given, the substring contains all charac- 
ters to the right of character position i in array m and is not terminated by 
a null byte. If len is given, the string is copied and terminated with a null 
byte. If len is equal to zero, out is replaced by the null string. The old 
contents of array out are lost when this routine is called. 

Errors: 

None. 

3.107 SUSPND (FB and XM Only) 

The SUSPND subroutine suspends main program execution of the current 
job and allows only completion routines (for I/O and scheduling requests) to 
run. 

Form: CALL SUSPND 

Notes: 

1. The monitor maintains a suspension counter for each job. This count is 
decremented by SUSPND and incremented by RESUME (see Section 
3.99). A job will actually be suspended only if this counter is negative. 
Thus, if a RESUME is issued before a SUSPND, the latter routine will 
return immediately. 

2. A program must issue an equal number of SUSPND and RESUME 
calls. 

3. A SUSPND subroutine call from a completion routine decrements the 
suspension counter but does not suspend the main program. If a comple- 
tion routine does a SUSPND, the main program continues until it also 
issues a SUSPND, at which time it is suspended. Two RESUME calls 
are then required to proceed. 

4. Because SUSPND and RESUME are used to simulate an ITWAIT (see 
Section 3.61) in the monitor, a RESUME issued from a completion rou- 
tine and not matched by a previously executed SUSPND can cause the 
main program execution to continue past a timed wait before the entire 
time interval has elapsed. 

For further information on suspending main program execution of the cur- 
rent job, see the .SPND programmed request (Section 2.84). 

Errors: 

None. 

Example: 

INTEGER IAREA(4) 

COMMON /RDBLK/ IBUF(25B) 

EXTERNAL RDFIN 
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IF(IREADF(256iIBUF»IBLK »ICHAN»IAREA.RDFIN) .NE.O) GOTO 1000 
C GOTO 1000 FOR ANY TYPE OF ERROR 
C 
C DO OVERLAPPED PROCESSING 



CALL SUSPND (SYNCHRONIZE WITH COMPLETION ROUTINE 



END 

SUBROUTINE RDFIN ( I ARGl . I ARGZ ) 

COMMON /RDBLK/ IBUF(25B) 



CALL RESUME ! CONTINUE MAIN PROGRAM 



END 



3.108 TIMASC 



The TIMASC subroutine converts a two-word internal format time into an 
ASCII string of the form: 

hh:mm:ss 

where: 

hh is the two-digit hours indication 

mm is the two-digit minutes indication 

ss is the two-digit seconds indication 
Form: CALL TIMASC (itime,strng) 
where: 

itime is the two-word internal format time to be converted. 
itime(l) is the high-order time, itime(2) is the low-order time 

strng is the eight-element array to contain the ASCII time 
Errors: 

None. 

Example: 

The following example determines the amount of time from the time 
the program is run until 5 p.m. and prints it. 

INTEGER*^ Jl »J2 .J3 
LOGICAL*! STRNG(B) 
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CALL JTIME<17»0>0>0»J1) 
CALL GTIM(J2) 
CALL JJCyKJl ) 
CALL JJCVT(J2) 
CALL JSUB( Jl >J2 tJ3> 
CALL JJCyT(J3) 
CALL TIMABC(J3>STRNG) 
TYPE 99»(BTRNG(I) tl=l t8) 
99 FORMAK' IT IS '»8Alt' TILL 5 P.M.') 



3.109 TIME 



The TIME subroutine returns the current system time of day as an eight- 
character ASCII string of the form: 

hh:mm:ss 
where: 

hh is the two-digit hours indication 

mm is the two-digit minutes indication 

ss is the two-digit seconds indication 
Form: CALL TIME (strng) 
where: 

strng is the eight-element array to receive the ASCII time 
Notes: 

A 24-hour clock is used (for example, 1:00 p.m. is represented as 13:00:00). 
Errors: 

None. 
Example: 

LOGICAL*! STRNG(B) 



CALL TIME(STRNG> 
TYPE 99»(STRNG(I) »I=1 »8) 
99 FORMAT (' IT IS NOW ',8A1) 



3.110 TRANSL 



The TRANSL routine performs character translation on a specified string 
and requires approximately 64(decimal) words on the R6 stack for its exe- 
cution. This space should be considered when allocating stack space. 

Form: CALL TRANSL (in,out,r[,p]) 
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where: 

in is the array containing the input string; it is terminated by a 
null byte 

out is the array to receive the translated string; it is not termi- 
nated by a null byte 

r is the array containing the replacement string; it is terminated 

by a null byte 

p is the array containing the characters in in to be translated; it 
is terminated by a null byte 

The string specified by array out is replaced by the string specified by array 
in, modified by the character translation process specified by arrays r and 
p. If any character position in in contains a character that appears in the 
string specified by p, it is replaced in out by the corresponding character 
from string r. If the array p is omitted, it is assumed to be the 127 seven-bit 
ASCII characters arranged in ascending order, beginning with the charac- 
ter whose ASCII code is 001. If strings r and p are given and differ in 
length, the longer string is truncated to the length of the shorter. If a 
character appears more than once in string p, only the last occurrence is 
significant. A character can appear any number of times in string r. 

Errors: 

None. 

Examples: 

The following example causes the string in array A to be copied to 
array B. All periods within A become minus signs, and all question 
marks become exclamation points. 

CALL TRANSL(A>B» '-!','.?') 

The following is an example of TRANSL being used to format charac- 
ter data. 

L0GICAL»1 STRING(27) ,RESULT(Z7) .PATRN(27) 
C SET UP THE STRING TO BE REFORMATTED 
C 

CALL SCOPYCTHE HORN BLOWS AT MIDN I GHT ' .STRING ) 
C SET UP NUMBER-CHARACTER DATA RELATIONSHIP 
C 

C 0000000001Uniini2222Z22 
C 123456789012345B7890123a5G 
C THE HORN BLOWS AT MIDNIGHT 
C NOW SET UP PATRN TO CONTAIN THE FOLLOWING PATTERN: 

C 16.17,16,19,20,21 .22,23,24,25,26,15,1 ,2,3,4,5,6,7,8,9,10,11 ,12,13,14,0 
C 

DO 10 1 = 16, 2G 
10 PATRN( I-15)=I 

PATRN(12)=15 

DO 20 1=1,14 
20 PATRN(I+12)=I 

PATRN(27)=0 
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c 

C THE FOLLOWING CALL TO TRANSL REARRANGES THE CHARACTERS OF 

C THE INPUT STRING TO THE ORDER SPECIFIED BY PATRN: 

C 

CALL TRANSL(PATRN (RESULT .STRING) 

C 

C RESULT NOW CONTAINS THE STRING 'AT MIDNIGHT THE HORN BLOWS' 

C IN GENERAL. THIS METHOD CAN BE USED TO FORMAT INPUT STRINGS 

C OF UP TO 127 CHARACTERS. THE RESULTANT STRING WILL BE 

C AB LONG AS THE PATTERN STRING (AS IN THE ABOyE EXAMPLE). 



3.111 TRIM 



The TRIM routine shortens a specified character string by removing all 
trailing blanks. A trailing blank is a blank that has no non-blanks to its 
right. If the specified string contains all blank characters, it is replaced by 
the null string. If the specified string has no trailing blanks, it is un- 
changed. 

Form: CALL TRIM (a) 

where: 

a is the array containing the string to be trimmed; it is terminated 
by a null byte on input and output 

Errors: 

None. 
Example: 

LaGICAL*l STRING(81) 
ACCEPT 100.(STRING(I) .1=1 .80) 
100 FORMAKBOAl) 

CALL SCOPY(STRING .STRING. 80) IMAKE ASCIZ 

CALL TRIM(STRING) ITRIM TRAILING BLANKS 



3.112 UNLOCK 



The UNLOCK subroutine releases the User Service Routine (USR) from 
memory if it was placed there by the LOCK routine. If the LOCK required 
a swap, the UNLOCK loads the user program back into memory. If the 
USR does not require swapping, the UNLOCK involves no I/O. The USR is 
always resident in XM. 

Form: CALL UNLOCK 

Notes: 

1. It is important that at least as many UNLOCK calls are given as 
LOCK calls. If more LOCK calls were done, the USR remains locked in 
memory. Extra UNLOCK calls are ignored. 

2. When running two jobs in the FB system, use the LOCK/UNLOCK 
pairs only when absolutely necessary. If one job locks the USR, the 
other job cannot use the USR until it is unlocked. 



System Subroutine Description and Examples 3-97 



3. In an FB system, calling the CSI (ICSI) with input coming from the 
console terminal performs a temporary implicit UNLOCK. 

For further information on releasing the USR from memory, see the 
.LOCK/.UNLOCK programmed requests (Section 2.41). 

Errors: 

None. 
Example: 



GET READY TO DO MANY USR OPERATIONS 
CALL LOCK IDISABLE USR SWAPPING 
PERFORM THE USR CALLS 



FREE THE USR 
CALL UNLOCK 



3.113 VERIFY 



The VERIFY routine checks that a given string is composed entirely of 
characters from a second string. If a character does not exist in the string 
being examined, VERIFY returns the position of the first character in the 
string being examined that is not in the source string. If all characters 
exist, VERIFY returns a 0. 



Form: CALL VERIFY (a,b,i) 
or 
i = IVERIF(a,b) 



where: 



a is the array containing the string to be scanned; it is terminated 
by a null byte 

b is the array containing the string of characters to be accepted in 
a; it is terminated by a null byte 



Function Result: 



= n 



If all characters of a exist in 6; also if a is a null string. 
Where n is the character position of the first character in 
array a that does not appear in array b; if 6 is a null string 
and a is not, i equals 1. 
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Example: 



The following example accepts a one- to five-digit unsigned decimal 
number and returns its value. 

L0GICAL»1 INSTR(81) 



CALL UERIFY(INSTR»'012345G789' .1) 
Fd.EO.l) STOP 'NUMBER MISSING' 
F(I.EO.O) I=LEN(INSTR) 
Fd.GT.S) STOP 'TOO MANY DIGITS' 

NUM=IVALUE(INSTR ,1) 



END 
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Appendix A 
Display File Handler 



This appendix describes the assembly language support provided under 
RT-11 for the VTll graphic display hardware systems. 

The following manuals are suggested for additional reference: 

GT40/GT42 User's Guide 
EK-GT40-OP-002 

GT44 User's Guide 

EK-GT44-OP-001 

VTll Graphic Display Processor 
EK-VTll-TM-001 

DECGRAPHIC-11 GT Series Reference Card 
EH-02784-73 

DECGraphic-11 FORTRAN Reference Manual 
DEC-11-GFRMA-A-D 

BASIC-U Graphics Extensions User's Guide 
DEC-11-LBGEA-A-D 



A.1 Description 



The graphics display terminals have hardware configurations that include a 
display processor and CRT (cathode ray tube) display. All systems are 
equipped with light pens and hardware character and vector generators, and 
are capable of high-quality graphics. The Display File Handler supports this 
graphics hardware at the assembly language level under the RT-11 monitor. 

A.1.1 Assembly Language Display Support 

The Display File Handler is not an RT-11 device handler, since it does not use 
the I/O structure of the RT-11 monitor. For example, it is not possible to use a 
utility program to transfer a text file to the display through the Display File 
Handler. Rather, the Display File Handler provides the graphics programmer 
the means for the display of graphics files and the easy management of the 
display processor. Included in its capabilities are such services as interrupt 
handling, light pen support, tracking object, and starting and stopping of the 
display processor. 

The Display File Handler manages the display processor by means of a base 
segment (called VTBASE) which contains interrupt handlers, an internal 
display file and some pointers and flags. The display processor cycles through 
the internal display file; any user graphics files to be displayed are accessed 
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by display subroutine calls from the Handler's display file. In this way, the 
Display File Handler exerts control over the display processor, relieving the 
assembly language user of the task. 

Through the Display File Handler, the programmer can insert and remove 
calls to display files from the Handler's internal display file. Up to two user 
files may be inserted at one time, and that number may be increased by re- 
assembling the Handler. Any user file inserted for display may be blanked 
(the subroutine call to it bypassed) and unblanked by macro calls to the 
Display File Handler. 

Since the Handler treats all user display files as graphics subroutines to its 
internal display file, a display processor subroutine call is required. This 
is implemented with software, using the display stop instruction, and 
is available for user programs. This instruction and several other extended 
instructions implemented with the display stop instruction are described in 
Section A. 3. 

The facilities of the Display File Handler are accessed through a file of macro 
definitions (VTMAC) which generate calls to a set of subroutines in VTLIB. 
VTMAC's call protocol is similar to that of the RT-11 macros. The expansion 
of the macros is shown in Section A.6. VTMAC also contains, for convenience 
in programming, the set of recommended display processor instruction 
mnemonics and their values. The mnemonics are listed in Section A. 7 and are 
used in the examples throughout this appendix. 

VTCALl through VTCAL4 are the set of subroutines which service the 
VTMAC calls. They include functions for display file and display processor 
management. These are described in detail in Section A.2. VTCALl through 
VTCAL4 are distributed, along with the base segment VTBASE, as a file of 
five object modules called VTHDLR.OBJ. VTHDLR is built into the graphics 
library VTLIB by using the monitor LIBRARY command. VTHDLR only 
supports VTll hardware. Section A.4.2 shows an example. 

A. 1.2 Monitor Display Support 

The RT-11 monitor, under Version 03 and later, directly supports the display 
as a console device. A keyboard monitor command, GT ON (GT OFF) per- 
mits the selection of the display as console device. Selection results in the 
allocation of approximately 1.25K words of memory for text buffer and code. 
The buffer holds approximately 2000 characters. 

The text display includes a bUnking cursor to indicate the position in the text 
where a character is added. 1 he cursor initially appears at the top left corner 
of the text area. As lines are added to the text the cursor moves down the 
screen. When the maximum number of lines are on the screen, the top line is 
deleted from the text buffer when the line feed terminating a new line is 
received. This causes the appearance of "scrolling," as the text disappears off 
the top of the display. 

When the maximum number of characters have been inserted in the text 
buffer, the scroller logic deletes a line from the top of the screen to make room 
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for additional characters. Text may appear to move (scroll) off the top of the 
screen while the cursor is in the middle of a line. 

The Display File Handler can operate simultaneously with the scroller pro- 
gram, permitting graphic displays and monitor dialogue to appear on the 
screen at the same time. It does this by inserting its internal display file into 
the display processor loop through the text buffer. However, the following 
should be noted. Under the SJ Monitor, if a program using the display for 
graphics is running with the scroller in use (that is, GT ON is in effect), and 
the program does a soft exit (.EXIT with RO not equal to 0) with the display 
stopped, the display remains stopped until a CTRL/C is typed at the key- 
board. 

This can be recognized by failure of the monitor to echo on the screen when 
expected. If the scroller text display disappears after a program exit, always 
type CTRL/C to restore. If CTRL/C fails to restore the display, the running 
program probably has an error. 

Four scroller control characters provide the user with the capability of halting 
the scroller, advancing the scrolling in page sections, and printing hard copy 
from the scroller. 

NOTE 

The scroller logic does not limit the length of a line, but the 
length of text lines affects the number of lines which may be 
displayed, since the text buffer is finite. As text lines become 
longer, the scroller logic may delete extra lines to make room 
for new text, temporarily decreasing the number of lines dis- 
played. 



A.2 Description of Graphics IVIacros 

The facilities of the Display File Handler are accessed through a set of macros, 
contained in VTMAC, which generate assembly language calls to the Handler 
at assembly time. The calls take the form of subroutine calls to the sub- 
routines in VTLIB. Arguments are passed to the subroutines through register 
and, in the case of the .TRACK call, through both register and the stack. 

This call convention is similar to Version 1 RT-11 I/O macro calls, except that 
the subroutine call instruction is used instead of the EMT instruction. If a 
macro requires an argument but none is specified, it is assumed that the 
address of the argument has already been placed in register 0. The program- 
mer should not assume that RO is preserved through the call. 

A.2.1 .BLANK 

The .BLANK request temporarily blanks the user display file specified in the 
request. It does this by bypassing the call to the user display file, which 
prevents the display processor from cycling through the user file, effectively 
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blanking it. This effect can later be canceled by the .RESTR request, which 
restores the user file. When the call returns, the user is assured the display 
processor is not in the file that was blanked. 

Macro Call: .BLANK faddr 

where: 

faddr is the address of the user display file to be blanked 
Errors: 

No error is returned. If the file specified was not found in the Handler 
file or has already been blanked, the request is ignored. 

A.2.2 .CLEAR 

The .CLEAR request initializes the Display File Handler, clearing out any 
calls to user display files and resetting all of the internal flags and pointers. 

After initialization with .LNKRT (Section A.2.4), the .CLEAR request can be 
used any time in a program to clear the display and to reset pointers. All calls 
to user files are deleted and all pointers to status buffers are reset. They must 
be re-inserted if they are to be used again. 

Macro Call: .CLEAR 



Errors: 



None. 



Example: 



This example uses a .CLEAR request to initialize the Handler then 
later uses the .CLEAR to re-initialize the display. The first .CLEAR is 
used for the case when a program may be restarted after a CTRL C or 
other exit. 



BR RSTRT 



Exi: 


BIS #20000,6*44 JSET RbtENTER BIT IN JSW 


RSTRT : 


.UNLNK 


5CLEARS LINK FLAG FOR RESTART 




.LNKRT 


rSET UP VECTORS » START DISPLAY 




.CLEAR 


{INITIALIZE HANDLER 




.INSRT #FILE1 


> DISPLAY A PICTURE 


1*: 


.TTYIN 


fWAIT FOR A KEY STRIKE 




CMPB *12»R0 


SLINE FEED? 




BNE 1* 


rNO, LOOP 




.CLEAR 


fYES, CLEAR DISPLAY 




.INSRT *FILE2 


> DISPLAY NEW PICTURE 


FILE It 


* 
♦ 

POINT 



500 


J AT POINT < 0,500) 








LONGV 


J DRAW A LINE 




500!INTX 



DRET 




rro (500,500) 
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FILE2: POINT JAT POINT (SOOkO) 

SOO 

LONCW 5 DRAW A LINE 

0!.i:ntx rTO (500*500) 

500 

IIRE7 



.END EXl 



A.2.3 .INSRT 

The .INSRT request inserts a call to the user display file specified in the 
request into the Display File Handler's internal display file. .INSRT causes 
the display processor to cycle through the user file as a subroutine to the 
internal file. The handler permits two user files at one time. The call inserted 
in the handler looks like the following: 

DJSR » DISPLAY SUBROUTINE 

.+4 J RETURN ADDRESS 

.fscidr jSUBROUTINE ADDRESS 

The call to the user file is removed by replacing its address with the address of 
a null display file. The user file is blanked by replacing the DJSR with a 
DJMP instruction, bypassing the user file. 

Macro Call: .INSRT faddr 

where: 

faddr is the address of the user display file to be inserted 

Errors: 

The .INSRT request returns with the C bit set if there was an error in 
processing the request. An error occurs only when the Handler's display 
file is full and cannot accept another file. If the user file specified exists, 
the request is not processed. Two display files with the same starting 
address cannot be inserted. 

Example: 

See the examples in Sections A. 2. 2 and A. 2. 4. 

A.2.4 .LNKRT 

The .LNKRT request sets up the display interrupt vectors and possibly links 
the Display File Handler to the scroll text buffer in the RT-11 monitor. It 
must be the first call to the Handler, and is used whether or not the RT-11 
monitor is using the display for console output (that is, the KMON command 
GT ON has been entered). 

The .LNKRT request used with Version 03 and later RT-11 monitors enables 
a display application program to determine the environment in which it is 
operating. Error codes are provided for the situations where there is no display 
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hardware present on the system or the display hardware is already being used 
by another task (for example, a foreground job in the foreground/background 
version). 

The existence of the monitor scroller and the size of the Handler's subpicture 
stack are also returned to the caller. If a previous call to .LNKRT was made 
without a subsequent .UNLNK, the .LNKRT call is ignored and an error code 
is returned. 

Macro Call: .LNKRT 

Errors: 

Error codes are returned in RO, with the N condition bit set. 

Code Meaning 

-1 No VTll display hardware is present on this system. 

-2 VTll hardware is presently in use. 

-3 Handler has already been linked. 

On completion of a successful .LNKRT request, RO will contain the 
display subroutine stack size, indicating the depth to which display 
subroutines may be nested. The N bit will be zero. 

If the RT-11 monitor scroll text buffer was not in memory at the time of 
the .LNKRT, the C bit will be returned set. The KMON commands GT 
ON and GT OFF cannot be issued while a task is using the display. 

Example: 



start: 


•LNKRT 






BMI 


ERROR 




BCS 


CONT 




.SCROL 


♦ SBUF 


CONTJ 


.INSRT 


♦FILEl 


i»: 


.TTYIN 






CMPB 


*12fR0 




BNE 


1* 




.UNLNK 






.EXIT 




sbuf: 


.BYTE 


5 




.BYTE 


7 




.WORD 


1000 


FlLEi: 


POINT 
500 
500 
CHAR 






.ASCII 


/FILEl Tl 




• EVEN 






BRET 











ERROR : 


Error re 


lutine 



JLINK TO MONITOR 

fERROR DOING LINK 

J NO SCROLL IF C SET 

> ADJUST SCROLL PARAMETERS 

f DISPLAY A PICTURE 

JWAIT FOR KEY STRIKE 

J LINE FEED? 

>N0» LOOP 

fYESr UNLINK AND EXIT 



J LINE COUNT OF 5 

» INTENSITY 7 (SCALE OF 1-8) 

f POSITION OF TOP LINE 

J AT POINT (SOOi-SOO) 



fDISPLAY SOME TEXT 
/FILEl THIS IS FILEl. TYPE CR TO EXIT/ 
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A.2.5 .LPEN 

The .LPEN request transfers the address of a Hght pen status data buffer to 
VTBASE. Once the buffer pointer has been passed to the Handler, the light 
pen interrupt handler in VTBASE will transfer display processor status data 
to the buffer, depending on the state of the buffer flag. 

The buffer must have seven contiguous words of storage. The first word is the 
buffer flag, and it is initially cleared (set to zero) by the .LPEN request. When 
a light pen interrupt occurs, the interrupt handler transfers status data to the 
buffer and then sets the buffer flag non-zero. The program can loop on the 
buffer flag when waiting for a light pen hit (although doing this will tie up the 
processor; in a foreground/background environment, timed waits would be 
more desirable). No further data transfers take place, despite the occurrence 
of numerous light pen interrupts, until the buffer flag is again cleared to zero. 
This permits the program to process the data before it is destroyed by another 
interrupt. 

The buffer structure looks like this: 

Buffer Flag 

Name 

Subpicture Tag 

Display Program Counter (DPC) 

Display Status Register (DSR) 

X Status Register (XSR) 

Y Status Register (YSR) 

The Name value is the contents of the software Name Register (described in 
A.3.5) at the time of interrupt. The Tag value is the tag of the subpicture 
being displayed at the time of interrupt. The last four data items are the 
contents of the display processor status registers at the time of interrupt. They 
are described in detail in Table A-1. 

Macro Call: .LPEN baddr 

where: 

baddr is the address of the 7-word light pen status data buffer 
Errors: 

None. 

If a .LPEN was already issued and a buffer specified, the new buffer 
address replaces the previous buffer address. Only one light pen buffer 
can be in use at a time. 



Example: 



.iNSiRT *L.F-ii...i:;: f display lf-ile 

.LPEN #LBUF iSEJ UP LPEN BUFFER 



loop: tst lbuf ptest lbuf flagv which 

BE« loop ?WILL be SET NON-ZERO 



iON LIGHT PEN HIT. 



r PROCESS DATA IN LBUF HERE. 
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L.BUF t 

lfile: 


CLR 

BR 
.BLKW 


LBUF 

LOOP 
7 


?DATA IN LBUF 

» CLEAR THE BUFFER FLAG 

f PERM IT TING ANOTHER "HIT" 

mo UAIT FOR IT 

f SEVEN UORll LPEN BUFFER 


Table A-1: 


Description 


of Display Status Words 




Bits 




Significance 



Display Program Counter (DPC=172000) 

0-15 Address of display processor program 

counter at time of interrupt. 

Display Status Register (DSR=172002) 

0-1 Line Type 

2 Spare 

3 Blink 

4 Italics 

5 Edge Indicator 

6 Shift Out 

7 Light Pen Flag 
8-10 Intensity 
11-14 Mode 

15 Stop Flag 



X Status Register (XSR=172004) 

0-9 

10-15 

Y Status Register (YSR=172006) 

0-9 

10-15 



X Position 
Graphplot Increment 

Y Position 
Character Register 



A.2.6 .NAME 

The .NAME request has been added to the Version 03 and later Display File 
Handler. The contents of the name register are now stacked when a subpic- 
ture call is made. When a light pen interrupt occurs, the contents of the name 
register stack may be recovered if the user program has supplied the address 
of a buffer through the .NAME request. 

The buffer must have a size equal to the stack depth (default is 10) plus one 
word for the flag. When the .NAME request is entered, the address of the 
buffer is passed to the Handler and the first word (the flag word) is cleared. 
When a light pen hit occurs, the stack's contents are transferred and the flag 
is set non-zero. 

Macro Call: .NAME baddr 

where: 

baddr is the address of the name register buffer 
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Errors: 

None. 

If a .NAME request has been previously issued, the new buffer address 
replaces the previous buffer address. 

A.2.7 .REMOV 

The .REMOV request removes the call to a user display file previously in- 
serted in the handler's display file by the .INSRT request. All reference to the 
user file is removed, unlike the .BLANK request, which merely bypasses the 
call while leaving it intact. 

Macro Call: .REMOV faddr 

where: 

faddr is the address of the display file to be removed 

Errors: 

No errors are returned. If the file address given cannot be found, the 
request is ignored. 

A.2.8 .RESTR 

The .RESTR request restores a user display file that was previously blanked 
by a .BLANK request. It removes the by-pass of the call to the user file, so 
that the display processor once again cycles through the user file. 

Macro Call: .RESTR faddr 

where: 

faddr is the address of the user file that is to be restored to view 

Errors: 

No errors are returned. If the file specified cannot be found, the request 
is ignored. 

A.2.9 .SCROL 

This request is used to modify the appearance of the Display Monitor's text 
display. The .SCROL request permits the programmer to change the maxi- 
mum line count, intensity and the position of the top line of text of the 
scroller. The request passes the address of a two-word buffer which contains 
the parameter specifications. The first byte is the line count, the second byte 
is the intensity, and the second word is the Y position. Line count, intensity 
and Y position must all be octal numbers. The intensity may be any number 
from to 7, ranging from dimmest to brightest. (If an intensity of is speci- 
fied, the scroller text will be almost unnoticeable at a BRIGHTNESS knob 
setting less than one-half.) The scroller parameter change is temporary, since 
an .UNLNK or CTRL/C restores the previous values. 



Display File Handler A-9 



Macro Call: .SCROL baddr 



where: 



baddr is the address of the two-word scroll parameters buffer 



Errors: 



No errors are returned. No checking is done on the values of the param- 
eters. A zero argument is interpreted to mean that the parameter value 
is not to be changed. A negative argument causes the default parameter 
value to be restored. 



Example: 



. SCROL 



•SCBUF 



f ADJUST SCROLL. PARAMETERS 



SCBUFJ 



♦BYTE 5 
.BYTE 
.UORD 300 



fDECREASE *LINES TO 5. 
CLEAVE INTENSITY UNCHANGED. 
JTOP LINE AT Y=300. 



A.2.10 .START 

The .START request starts the display processor if it was stopped by a .STOP 
directive. If the display processor is running, it is stopped first, then restarted. 
In either case, the subpicture stack is cleared and the display processor is 
started at the top of the handler's internal display file. 

Macro Call: .START 



Errors: 



None. 



A.2.11 .STAT 

The .STAT request transfers the address of a seven-word status buffer to the 
display stop interrupt routine in VTBASE. Once the transfer has been made, 
display processor status data is transferred to the buffer by the display stop 
interrupt routine in VTBASE whenever a .DSTAT or .DHALT instruction is 
encountered (see Sections A. 3. 3 and A. 3. 4). The transfer is made only when 
the buffer flag is clear (zero). After the transfer is made, the buffer flag is set 
non-zero and the .DSTAT or .DHALT instruction is replaced by a .DNOP 
(Display NOP) instruction. 

The status buffer must be a seven-word, contiguous block of memory. Its 
contents are the same as the light pen status buffer. For a detailed description 
of the buffer and an explanation of the status words, see Section A. 2. 5 and 
Table A-1. 

Macro Call: .STAT baddr 

where: 

baddr is the address of the status buffer receiving the data 
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Errors: 

No errors are indicated. If a buffer was previously set up, the new buffer 
address is replaced as the old buffer address. 

A.2.12 .STOP 

The .STOP request "stops" the display processor. It actually effects a stop by 
preventing the DPU from cycling through any user display files. It is useful for 
stopping the display during modification of a display file, a risky task when 
the display processor is running. However, a .BLANK could be equally useful 
for this purpose, since the .BLANK request does not return until the display 
processor has been removed from the user display file being blanked. 

Macro Call: .STOP 

Errors: 

None. 

NOTE 

Since the display processor must cycle through the text buffer 
in the Display Monitor in order for console output to be pro- 
cessed, the text buffer remains visible after a .STOP request is 
processed, but all user files disappear. 

A.2.13 .SYNC/.NOSYN 

The .SYNC and .NOSYN requests provide program access to the power line 
synchronization feature of the display processor. The .SYNC request enables 
synchronization and the .NOSYN request disables it (the default case). 

Synchronization is achieved by stopping the display and restarting it when 
the power line frequency reaches a trigger point, e.g., a peak or zero- crossing. 
Synchronization has the effect of fixing the display refresh time. This may be 
useful in some cases where small amounts of material are displayed but the 
amount frequently changes, causing changes in intensity. In most cases, how- 
ever, using synchronization increases flicker. 

Macro Calls: .SYNC 
.NOSYN 

Errors: 

None. 

A.2.14 .TRACK 

The .TRACK request causes the tracking object to appear on the display CRT 
at the position specified in the request. The tracking object is a diamond- 
shaped display figure which is light-pen sensitive. If the light pen is placed 
over the tracking object and then moved, the tracking object follows the light 
pen, trying to center itself on the pen. 
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The tracking object first appears at a position specified in a two-word buffer 
whose address was supplied with the .TRACK request. As the tracking object 
moves to keep centered on the light pen, the new center position is returned 
to the buffer. A new set of X and Y values is returned for each light pen 
interrupt. 

The tracking object cannot be lost by moving it off the visible portion of the 
display CRT. When the edge flag is set, indicating a side of the tracking object 
is crossing the edge of the display area, the tracking object stops until moved 
toward the center. To remove the tracking object from the screen, repeat the 
.TRACK request without arguments. 

The .TRACK request may also include the address of a completion routine as 
the second argument. If a .TRACK completion routine is specified, the light 
pen interrupt handler passes control to the completion routine at interrupt 
level. The completion routine is called as a subroutine and the exit statement 
must be an RTS PC. The completion routine must also preserve any registers 
it may use. 

Macro Call: .TRACK baddr, croutine 
where: 

baddr is the address of the two-word buffer containing the X and Y 
position for the track object 

croutine is the address of the completion routine 

Errors: 

None. 

Example: 

See Section A. 10. 

A.2.15 .UNLNK 

The .UNLNK request is used before exiting from a program. In the case where 
the scroller is present, .UNLNK breaks the link, established by .LNKRT, 
between the Display File Handler's internal display file and the scroll file in 
the Display Monitor. The display processor is started cycling in the scroll text 
buffer, and no further graphics may be done until the link is established 
again. In the case where no scroller exists, the display processor is simply left 
stopped. 

Macro Call: .UNLNK 

Errors: 

No errors are returned. An internal link flag is checked to determine if 
the link exists. If it does not exist, the request is ignored. 
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A. 3 Extended Display Instructions 

The Display File Handler offers the assembly language graphics programmer 
an extended display processor instruction set, implemented in software 
through the use of the Load Status Register A (LSRA) instruction. The ex- 
tended instruction set includes: subroutine call, subroutine return, display 
status return, display halt, and load name register. 

A. 3.1 DJSR Subroutine Call instruction 

The DJSR instruction (octal code is 173400) simulates a display subroutine 
call instruction by using the display stop instruction (LSRA instruction with 
interrupt bits set). The display stop interrupt handler interprets the non-zero 
word following the DJSR as the subroutine return address, and the second 
word following the DJSR as the address of the subroutine to be called. The 
instruction sequence is: 

DJSR 

Return address 

Subroutine address 

Example: 

To call a subroutine SQUARE: 

POINT ^POSITION BEAM 

100 fAT (lOOrlOO) 

100 

DJSR PTHEN CALL SUBROUTINE 

.+4 

SQUARE 5 TO DRAW A SQUARE 

DRET 



The use of the return address preceding the subroutine address offers 
several advantages. For example, the BASIC-11 graphics software uses 
the return address to branch around subpicture tag data stored follow- 
ing the subpicture address. This structure is described in Section A. 5. 3. 
In addition, a subroutine may be temporarily bypassed by replacing the 
DJSR code with a DJMP instruction, without the need to stop the 
display processor to make the by-pass. 

The address of the return address is stacked by the display stop inter- 
rupt handler on an internal subpicture stack. The stack depth is condi- 
tionalized and has a default depth of 10. If the stack bottom is reached, 
the display stop interrupt handler attempts to protect the system by 
rejecting additional subroutine calls. In that case, the portions of the 
display exceeding the legal stack depth will not be displayed. 

A.3.2 DRET Subroutine Return Instruction 

The DRET instruction provides the means for returning from a display file 
subroutine. It uses the same octal code as DJSR, but with a single argument 
of zero. The DRET instruction causes the display stop interrupt handler to 
pop its subpicture stack and fetch the subroutine return address. 
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Example: 
square: 



lOOIINTX 



OIINTX 

100 

lOOIINTXIMINUSX 



OilNTX 

lOOIMINUSX 

DRET 





$DRAU A SQUARE 



f RETURN FROM SUBPICTURE 



A.3.3 DSTAT Display Status Instruction 

The DSTAT instruction (octal code is 173420) uses the LSRA instruction to 
produce a display stop interrupt, causing the display stop interrupt handler to 
return display status data to a seven-word user status buffer. The status 
buffer must first have been set up with a .STAT macro call (if not, the 
DSTAT is ignored and the display is resumed). The first word of the buffer is 
set non-zero to indicate the transfer has taken place, and the DSTAT is 
replaced with a DNOP (display NOP). The first word is the buffer flag and 
the next six words contain name register contents, current subpicture tag, 
display program counter, display status register, display X register, and dis- 
play Y register. After transfer of status data, the display is resumed. 



A.3.4 DHALT Display Halt Instruction 

The DHALT instruction (octal code is 173500) operates similarly to the 
DSTAT instruction. The difference between the two instructions is that the 
DHALT instruction leaves the display processor stopped when exiting from 
the interrupt. A status data transfer takes place provided the buffer was 
initialized with a .STAT call. If not, the DHALT is ignored. 

Example: 



1$: 



.STAT #SBUF 

MOV #DHALT»STPLOC 

,INSRT *tiFILE 

TST SBUF 

BEQ 1$ 



fINIT BUFFER 

5 INSERT DHALT 

f DISPLAY THE PICTURE 

f DHALT PROCESSED? 

SNO» WAIT 



sbuf; 
dfile: 



STPLOCJ 



.BLKW 7 

POINT 

.WORD 

L0N6V 

.UORD 

DNOP 

DRET 





500 » 1350 
0^400 



fSTATUS BUFFER 

fPOSITION NEAR TOP OF 12" TUBE 

fDRAU A LINE» MAYBE OVER EDGE 
rIF IT IS A 12" SCOPE* 
J STATUS WILL BE RETURNED AT 
fTHIS POINT 



A.3.5 DNAME Load Name Register Instruction 

The Display File Handler provides a name register capability through the use 
of the display stop interrupt. When a DNAME instruction (octal code is 
173520) is encountered, a display stop interrupt is generated. The display stop 
handler stores the argument following the DNAME instruction in an internal 
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software register called the "name register." The current name register con- 
tents are returned whenever a DSTAT or DHALT is encountered, and more 
importantly, whenever a light pen interrupt occurs. The use of a "name" 
(with a valid range from 1 to 77777) enables the programmer to label each 
element of the display file with a unique name, permitting the easy identifica- 
tion of the particular display element selected by the light pen. 

The name register contents are stacked on a subpicture call and restored on 
return from the subpicture. 

Example: 

The SQUARE subroutine with "named" sides. 

square: dname >nahe is 

10 »io 

LONGV J DRAW A SIDE 

lOOIINTX 



DNAME rTHIS SIDE IS NAMED 

11 »11 

OIINTX J STILL IS LONG SECTOR MODE 

100 

DNAME 

12 

lOOIINTXIMINUSX 



DNAME 

13 

OIINTX 

lOOIMINUSX 

riRET f RETURN FROM SUBPICTURE 





A.4 Using the Display File Handler 

Graphics programs which intend to use the Display File Handler for display 
processor management can be written in MACRO assembly language. The 
display code portions of the program may use the mnemonics described in 
Section A.7. Calls to the Handler should have the format described in 
Section A.6. 

The Display File Handler is supplied in two pieces, a file of MACRO defini- 
tions and a library containing the Display File Handler modules. 

MACRO Definition File: VTMAC.MAC 

Display File Handler: VTLIB.OBJ (consisting of:) 

VTBASE.OBJ 
VTCALl.OBJ 
VTCAL2.0BJ 
VTCAL3.0BJ 
VTCAL4.0BJ 
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A. 4.1 Assembling Graphics Programs 

To assemble a graphics program using the display processor mnemonics or the 
Display Handler macro calls, the file VTMAC.MAC must be assembled with 
the program, and must precede the program in the assembler command 
string. 

Example: 

Assume PICTUR.MAC is a user graphics program to be assembled. An 
assembler command string would look like this: 

MACRO VTMAC+PICTUR/OBJECT 

A. 4. 2 Linking Graphics Programs 

Once assembled with VTMAC, the graphics program must be linked with the 
Display File Handler, which is supplied as a single concatenated object mod- 
ule, VTHDLR.OBJ. The Handler may optionally be built as a library, follow- 
ing the directions in A.8.5. The advantage of using the library when linking is 
that the Linker will select from the library only those modules actually used. 
Linking with VTHDLR.OBJ results in all modules being included in the link. 

To link a user program called PICTUR.OBJ using the concatenated object 
module supplied with RT-11: 

LINK PICTUR»VTHDLR 

To link a program called PICTUR.OBJ using the VTLIB library built by 
following the directions in A.8.5, be sure to use the Version 03 Linker: 

LINK PICTURfVTLIB 



VTLIB (Handler Modules): 

Module CSECT Contains 



Globals 



VTCALl 


$GT1 


.CLEAR 


$VINIT 






.START 


$VSTRT 




.STOP 


$VSTOP 








.INSRT 


$VNSRT 






.REMOV 


$VRMOV 


VTCAL2 


$GT2 


.BLANK 


$VBLNK 






.RESTR 


$VRSTR 


VTCAL3 


$GT3 


.LPEN 


$VLPEN 






.NAME 


$NAME 






.STAT 


$VS'i'PM 






.SYNC 


$SYNC 






.NOSYN 


INOSYN 






.TRACK 


$VTRAK 


VTCAL4 


$GT4 


.LNKRT 


$VRTLK 






.UNLNK 


$VUNLK 






.SCROL 


$VSCRL 


VTBASE 


$GTB 


Interrupt handlers 
and internal 
display file 


$DFILE 
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The file modules in VTHDLR can be used in three different ways. When space 
is not critical, the most straightforward way is to link VTHDLR directly with 
a display program. The following command is an example. 

LINK PlCTURr VTHDLR 

It is often necessary to conserve space, however, and selective loading of 
modules is possible by first creating an indexed object module library from 
VTHDLR and then by making global calls within the display program. The 
following command creates an indexed object module library. 

LIBRARY/CREATE yTLIB VTHDLR 

To further conserve space with overlays, it is also possible to extract individ- 
ual object modules from a library and create separate object module files. For 
example, to link a display program using overlays, the following statements 
are a typical sequence of creating, extracting and linking commands. (NOTE: 
the modules VTCALl and VTCAL2 must be in the same overlay if any global 
in either one is used.) 



♦LIBRARY/CREATE VTLIB VTHDLR 



.LIBRARY/EXTRACT VTLIB VTCALl 

GLOBAL? $VSTRT ! moves entire ntiodule with *VSTRT to VTCALl 

GLOBAL? ! Terminates promptind secsuence 

♦LIBRARY/EXTRACT VTLIB VTCAL2 

GLOBAL? *VBLNK ! Moves the entire module to VTCAL2 

GLOBAL? 

♦LIBRARY/EXTRACT VTLIB VTCALS 

GLOBAL? *VLPEN ! Moves the entire module 

GLOBAL? 

.LIBRARY/EXTRACT VTLIB VTCAL4 

GLOBAL? *VRTLK" ! Moves the entire module 

GLOBAL? 

.LIBRARY/EXTRACT VTLIB VTBASE 

GLOBAL? *DFILE ! Moves the entire module 
GLOBAL? 



.LINK/PROMPT PICTUR»VTBASE 
*VTCAL1 > VTCAL2» VTCAL3/0 J 1 
sKVTCAL4/0:i 
*// 



A. 5 Display File Structure 



The Display File Handler supports a variety of display file structures, takes 
over the job of display processor management for the programmer, and may 
be used for both assembly language graphics programming and for systems 
program development. For example, the Handler supports the tagged subpic- 
ture file structure used by the BASIC-11 graphics software, as well as simple 
file structures. These are discussed in this section. 
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A. 5.1 Subroutine Calls 

A subroutine call instruction, with the mnemonic DJSR, is implemented us- 
ing the display stop (DSTOP) instruction with an interrupt. The display stop 
interrupt routine in the Display File Handler simulates the DJSR instruction, 
and this allows great flexibility in choosing the characteristics of the DJSR 
instruction. 

The DJSR instruction stops the display processor and requests an interrupt. 
The DJSR instruction may be followed by two or more words, and in this 
implementation the exact number may be varied by the programmer at any 
time. The basic subroutine call has this form: 

DJSR 

Return Address 

Subroutine Address 

In practice, simple calls to subroutines could look like: 

DJSR 

. WORIi . +4 

.UORIi SUB 

where SUB is the address of the subroutine. Control will return to the display 
instruction following the last word of the subroutine call. This structure per- 
mits a call to the subroutine to be easily by-passed without stopping the 
display processor, by replacing the DJSR with a display jump (DJMP) in- 
struction: 

njMP 

.WORD ,+4 
.UORD SUD 

A more complex display file structure is possible if the return address is 
generalized: 

. DJSR 

.WORD NEXT 

. WORD SUB 

where NEXT is the generalized return address. This is equivalent to the 
sequence: 

DJSR 

.WORD .+4 

.WORD SUB 

DJMP 

.WORD NEXT 

It is also possible to store non-graphic data such as tags and pointers in the 
subroutine call sequence, such as is done in the tagged subpicture display file 
structure of the BASIC-11 graphics software. This technique looks like: 

DJSR 

.WORD NEXT 

.WORD SUB 

DATA 

next: 



For simple applications where the flexibility of the DJSR instruction de- 
scribed above is not needed and the resultant overhead is not desired, the 
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Display File Handler (VTBASE.MAC and VTCALL.MAC) can be condition- 
ally re-assembled to produce a simple DJSR call. If NOTAG is defined during 
the assembly, the Handler will be configured to support this simple DJSR 
call: 



rusR 

. WORD 



SUB 



where SUB is the address of the subroutine. Defining NOTAG will eliminate 
the subpicture tag capability, and with it the tracking object, which uses the 
tag feature to identify itself to the light pen interrupt handler. 

Whatever the DJSR format used, all subroutines and the user main file must 
be terminated with a subroutine return instruction. This is implemented as a 
display stop instruction (given the mnemonic DRET) with an argument of 
zero. A subroutine then has the form: 

SUB J Display Code 
DRET 
.WORD 



A.5.2 Main File/Subroutine Structure 

A common method of structuring display files is to have a main file which 
calls a series of display subroutines. Each subroutine will produce a picture 
element and may be called many times to build up a picture, producing 
economy of code. If the following macros are defined: 



.MACRO 


CALL <arg: 


DJSR 




.WORD 


.+4 


. WORD 


ARG 


.ENDM 




.MACRO 


RETURN 


DRET 




.WORD 





.ENDM 





then a main file/subroutine file structure would look like: 



SMAIN DISPLAY FILE 

i 

MAIN{ Displaw Code 
CALL SUB! 
Display Code 
CALL SUB2 



fiCALL SUBROUTINE 1 

fCALL SUBROUTINE 2 
J ETC 



J DISPLAY 



SUBIJ 



SUB2t 



RETURN 
SUBROUTINES 

Display Code 
RETURN 

Display Code 
RETURN 



{SUBROUTINE 1 

5 SUBROUTINE 2 
J ETC. 
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A.5.3 BASIC-11 Graphic Software Subroutine Structure 

An example of another method of structuring display files is the tagged sub- 
picture structure used by BASIC-11 graphic software. The display file is 
divided into distinguishable elements called subpictures, each of which has its 
own unique tag. 

The subpicture is constructed as a subroutine call followed by the subroutine. 
It is essentially a merger of the main file/subroutine structure into an in-line 
sequence of calls and subroutines. As such, it facilitates the construction of 
display files in real time, one of the important advantages of BASIC-11 
graphic software. 

The following is an example of the subpicture structure. Each subpicture has 
a call to a subroutine with the return address set to be the address of the next 
subpicture. The subroutine called may either immediately follow the call, or 
may be a subroutine defined as part of a subpicture created earlier in the 
display file. This permits a subroutine to be used by several subpictures 
without duplication of code. Each subpicture has a tag to identify it, and it is 
this tag which is returned by the light pen interrupt routine. To facilitate 
finding subpictures in the display file, they are made into a linked list by 
inserting a forward pointer to the next tag. 

SUBi: DJSR JSTART OF SUBPICTURE 1 

.WORD SUB2 iHEXr SUBPICTURE 

.WORD SUBl+12 >JUMP TO THIS SUBPICTURE 

♦WORD 1 JTA6 = 1 

.WORD SUB2+A ^POINTER TO NEXT TAG 



fBODY OF SUBPICTURE 1 

BRET 




SUB2 : DJSR 
. UORD 
.UORD 
«UORD 
.UORD 

J BODY OF SUBPICTURE 

DRET 
.WORD 



SUB3} 



SUB4 : 



DJSR 
. WORD 
.WORD 

• WORD 
. UORD 

DJSR 



SUB3 
SUB2+1; 
2 
SUB3f-6 



SUB4 
SUBl+12 

3 
SUB4+6 



rRETURN FROM 
$ SUBPICTURE 1 

J START SUBPICTURE 2 

JNEXT SUBPICTURE 

rJUMP TO THIS SUBPICTURE 

>TAG 2 

5PTR TO NEXT TAG 



5 RETURN FROM 
f SUBPICTURE 2 

5 START SUBPICTURE 3 
5 NEXT SUBPICTUFJE 
fCOPY SUBPICTURE 1 
?FOR THIS SUBPICTURE 
fBUT TAG IT 3. 
fPTR TO NEXT TAG 

J START SUBPICTURE 4 
fETC. 
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A.6 Summary of Graphics MACRO Calls 



Mnemonic 


Function 


MACRO Call 
(see Note 1) 


Assembly Language 

Expansion 

(see Note 2) 


.BLANK 


Temporarily blanks 
a user display file. 


.BLANK faddr 


.GLOBL IVBLNK 

.IF NB, faddr 

MOV faddr, "100 

.ENDC 

JSR "07, $VBLNK 


.CLEAR 


Initializes handler. 


.CLEAR 


.GLOBL $VINIT 
JSR "07, $VINIT 


.INSRT 


Inserts a call to 
user display file 
in handler's master 
display file. 


.INSRT faddr 


.GLOBL $VNSRT 

.IF NB, faddr 

MOV faddr, "OO 

.ENDC 

JSR "07, $VNSRT 


.LNKRT 


Sets up vectors and 
links display file 
handler to RT-11 
scroller. 


.LNKRT 


.GLOBL $VRTLK 
JSR "07, $VRTLK 


.LPEN 


Sets up light pen 
status buffer. 


.LPEN baddr 


.GLOBL $VLPEN 

.IF NB, baddr 

MOV baddr, "OO 

.ENDC 

JSR "07, $VLPEN 


.NAME 


Sets up buffer to 
receive name 
register stack 
contents. 


.NAME \baddr 


.GLOBL $NAME 

.IF NB, baddr 

MOV .BEDDR, 'OO 

.ENDC 

JSR "07, $NAME 


.NOSYN 


Disables power line 
synchronization. 


.NOSYN 


.GLOBL $NOSYN 
JSR "07, $NOSYN 


.REMOV 


Removes the call to 
a user display file. 


.REMOV faddr 


.GLOBL $VRMOV 

.IF NB, faddr 

MOV faddr, "OO 

.ENDC 

JSR "07, $VRMOV 


.RESTR 


Unblanks the user 
display file. 


.RESTR faddr 


.GLOBL $VRSTR 

IF NB, faddr 

MOV faddr, "OO 

ENDC 

JSR "07, $VRSTR 


.SCROL 


Adjusts monitor 
scroller parameters. 


.SCROL baddr 


.GLOBL $VSCRL 
.IF NB, baddr 
MOV baddr, "OO 
.ENDC 

JSR "07, $VSCRL 



Display File Handler A-21 



Mnemonic Function 

.START Starts the display. 



.STAT Sets up status 

buffer. 



.STOP Stops the display. 



.SYNC 



.TRACK 



.UNLNK 



Enables power line 
synchronization. 

Eaables the track 
object. 



Unlinks display 
handler from RT-11 
if linked (otherwise 
leaves display stopped). 



MACRO Call 
(see Note 1) 

.START 
.STAT baddr 



.STOP 

.SYNC 



.TRACK baddr, 
croutine 



.UNLNK 



Assembly Language 

Expansion 

(see Note 2) 

.GLOBL $VSTRT 
JSR *07, $VSTRT 

.GLOBL $VSTPM 

.IF NB, baddr 

MOV baddr, 'OO 

.ENDC 

JSR '07, $VSTPM 

.GLOBL $VSTOP 
JSR '07, $VSTOP 

.GLOBL $SYNC 
JSR '07, $SYNC 

.GLOBL $VTRAK 

IF NB, baddr 

MOV baddr, 'OO 

•ENDC 

.IF NB, croutine 

MOV croutine,- 

(-06) 

.IFF 

CLR-("06) 

.ENDC 

.NARG T 

.IF EQ, T 

CLR 'OO 

.ENDC 

JSR '07, $VTRAK 

.GLOBL $VUNLK 
JSR "07, $VUNLK 



NOTE 1 
baddr Address of data buffer, 
faddr Address of start of user display file, 

croutine Address of .TRACK completion routine. 

NOTE 2 

The lines preceded by a dot will not be assembled. 
The code they enclose may or may not be assembled 
depending on the conditionals. 
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A.7 Display Processor Mnemonics 



Mnemonic 


Value 


Function 


CHAR 


100000 


Character Mode 


SHORTY 


104000 


Short Vector Mode 


LONGV 


110000 


Long Vector Mode 


POINT 


114000 


Point Mode 


GRAPHX 


120000 


Graphplot X Mode 


GRAPHY 


124000 


Graphplot Y Mode 


RELATV 


130000 


Relative Point Mode 


INTO 


2000 


Intensity (Dim) 


INTl 


2200 


Intensity 1 


INT2 


2400 


Intensity 2 


INT3 


2600 


Intensity 3 


INT4 


3000 


Intensity 4 


INT5 


3200 


Intensity 5 


INT6 


3400 


Intensity 6 


INT7 


3600 


Intensity 7 (Bright) 


LPOFF 


100 


Light Pen Off 


LPON 


140 


Light Pen On 


BLKOFF 


20 


Blink Off 


BLKON 


30 


Blink On 


LINEO 


4 


Solid Line 


LINEl 


5 


Long Dash 


LINE2 


6 


Short Dash 


LINES 


7 


Dot Dash 


DJMP 


160000 


Display Jump 


DNOP 


164000 


Display No Operation 


STATSA 


170000 


Load Status A 
Instruction 


LPLITE 


200 


Light Pen Hit On 


LPDARK 


300 


Light Pen Hit Off 


ITALO 


40 


Italics Off 


ITALl 


60 


Italics On 


SYNC 


4 


Halt and Resume 
Synchronized 


STATSB 


174000 


Load Status B 
Instruction 



INCR 



100 



Graphplot Increment 



Vector/Point Mode 






INTX 


= 


40000 


Intensity Vector or 
Point 


MAXX 
MAXY 


= 


1777 
1377 


Maximum X Component 
Maximum Y Component 


MINUSX 
MINUSY 


= 


20000 
20000 


Negative X Component 
Negative Y Component 
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Mnemonic Value Function 

Short Vector Mode 

SHIFTX = 200 

MAXSX = 17600 Maximum X Component 

MAXSY = 77 Maximum Y Component 

MISVX = 20000 Negative X Component 

MISVY = 100 Negative Y Component 



A. 8 Assembly Instructions 

A. 8.1 General Instructions 

All programs can be assembled in 16K, using RT-11 MACRO. All assemblies 
and all links should be error free. The following conventions are assumed: 

1. Default file types are not explicitly typed. These are .MAC for source files, 
.OBJ for assembler output, and .SAY for Linker output. 

2. The default device (DK) is used for all files in the example command 
strings. 

3. Listings and link maps are not generated in the example command 
strings. 

A.8.2 VTBASE 

To assemble VTBASE with RT-11 link-up capability. 

MACKO VTBASE 

A.8.3 VTCAL1 - VTCAL4 

To assemble the modules VTCALl through VTCAL4: 

MACRO VTCAU , VTCAL2 , VTCAL3 r VTCAI,.4 

A.8.4 VTHDLR 

To create the concatenated handler module: 

COPY/BINARY VTCALl .0BJ»VTCAL2, OBJ, yTCAL3. OBJ, ~ 
VTCAL4 . OBJ , VTBASE . OBJ VTHDLR . OBJ 

A.8.5 Building VTLIB.OBJ 

To build the VTLIB library: 

LIBRARY/CREATE VTLIB VTHDLR 
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A.9 VTMAC 



.TITLE VTMAC 
i THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY ONLY BE USED 
', OR COPIED IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE. 

I COPYRIGHT <C) 1978» DIGITAL EQUIPMENT CORPORATION. 

I VTMAC IS A LIBRARY OF MACRO CALLS AND MNEMONIC DEFINITIIONS WHICH 
} PROVIDE SUPPORT OF THE VTll DISPLAY PROCESSOR. THE MACROS PRODUCE 
i CALLS TO THE VTll DEVICE SUPPORT PACKAGE, USING GLOBAL REFERENCES, 

r MACRO TO GENERATE A MACRO WITH ZERO ARGUMENTS. 
.MACRO MACO NAME r CALL 

.MACRO NAME 

.GLOBL CALL 
JSR PC » CALL 

.ENDM 
.ENDM 

i MACRO TO GENERATE A MACRO WITH ONE ARGUMENT 

.MACRO MACl NAME » CALL 

.MACRO NAME ARG 

.IF NBrARG 

MOV ARC/C'-OO 

. ENDC 

.GLOBL CALL 

JSR PC » CALL 

.ENDM 
.ENDM 

i MACRO TO GENERATE A MACRO WITH TWO OPTIONAL ARGUMENTS 

.MACRO MAC2 NAME, CALL 

.MACRO NAME ARG1,ARG2 
.GLOBL CALL 
.IF NBfARGl 





MOV ARGlr%"00 




.ENDC 




.IF NBfARG2 




MOV ARG2,-(SP) 




.IFF 




CLR -(SP> 




.NARG T 




.IF EQ»T 




CLR %"00 




.ENDC 




.ENDC 




JSR PC, CALL 




.ENDM 


.ENDM 




i MACRO 


LIBRARY FOR VTll J 


MACO 


<.CLEAR>,<«VINIT> 


MACO 


<.ST0P>,<*VSTOP> 


MACO 


<. start::-, <«VSTRT> 


MACl 


<.INSRT>,<*VNSRT> 


MACl 


< . REMOV> , <*VRMOV> 


MACl 


<.BLANK>,<*VBLNK> 


MACl 


<.RESTR>,<*VRSTR> 


MACl 


<.STAT>,<*VSTPM> 


MACl 


<.LPEN>,<*VLPEN> 
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MACl 
MAC2 
MACO 
MACO 


<.scrol:: 
< . track:; 
< . lnkrt:; 
< . unlnk::: 


■-f 
■■f 
'■ f ■ 
• r '■ 


••:*VSCRL. 

s:*vtrak: 
's'*vrti..k: 
•'^vunlk: 


5 MNEMONIC riEFINlTIONS F( 



the MT:l.l D:tSPLAY PROCESSOR 



DJMP= 160000 
tiNOP= 164000 
njSR= 173400 
tiRET = l 73400 
tiNAME = 173520 
11STAT=173420 
DHALT=-173500 



CHAR-=1 
SHORTM 
LONGV= 
POINT= 
GRAPHX 
6RAPHY 
RELATV 



00000 

104000 
110000 
114000 
••=^120000 
=124000 
-130000 



INTO= 
1NT1 = 
INT2= 
]:NT3= 
INT4 = 
INTS" 
INT6= 
INT7= 



=2000 
=2200 
=2400 
=2600 
=3000 
^3200 
3400 
3600 



CALL 
RETURN 



» DISPLAY JUMP 

P DISPLAY NOP 

-DISPLAY SUBROUTINE 

5 DISPLAY SUBROUTINE 

5SET NAME REGISTER 

f RETURN STATUS DATA 

{STOP DISPLAY AND RETURN 

f CHARACTER MODE 

f SHORT VECTOR MODE 

?LONG VECTOR MODE 

; POINT MODE 

; GRAPH X MODE 

r GRAPH Y MODE 

-RELATIVE VECTOR MODE 

{INTENSITY 



STATUS DATA 



LP0FF=100 

LP0N=140 

BLK0FF=20 

BLK0N=30 

LINE0=4 

LINE1=5 

LINE2=:6 

LINE3=7 

STATSA==170000 

LPLITE=200 

LPDARK=300 

ITAL0=40 

ITAL1=60 

SYNC=4 

STATSB=174000 

INCR=100 

INTX=40000 

MAXX=1777 

MAXY=1377 

MINUSX=20000 

MINUSY=20000 

MAXSX=17600 

MAXSY=77 

MISVX=20000 

MISVY=100 



{LIGHT PEN OFF 
{LIGHT PEN ON 
{BLINK OFF 
{BLINK ON 
{SOLID LINE 
{LONG DASH 
{SHORT DASH 
{DOT DASH 

{LOAD STATUS REG A 
{INTENSIFY ON LPEN HIT 
{DON'T INTENSIFY 
{ITALICS OFF 
{ITALICS ON 
{POWER LINE SYNC 

{LOAD STATUS REG D 
{GRAPH PLOT INCREMENT 
{INTENSIFY VECTOR OR POINT 
{MAXIMUM X INCR. •:= LONRV 
{MAXIMUM Y INCR. =■= LONGV 
{NEGATIVE X INCREMENT 
{NEGATIVE Y INCREMENT 
{MAXIMUM X INCR, = SHORTV 
{MAXIMUM Y INCR. = SHORTV 
{NEGATIVE X INCR. - SHORTV 
{NEGATIVE Y INCR. = SHORTV 
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Appendix B 

System Macro Library 



This appendix contains the listing of the system macro library (SYS- 
MAC.SML) for Version 5 of RT-11. This library is stored on the system 
device. It is used by MACRO when expanding the programmed requests 
and calling the subroutines that are described in Chapter 2. 

• MCALL .MODULE „ , • u v itr-vcc 

.MODULE SYSMAC tRELEASE = Y05»'.'ERSI0N=ll tCOMMENT = <Systeiii macro 1 i b ra ry > »L IB-Ytb 

COPYRIGHT (c) 1982* 19B3 BY 
DIGITAL EQUIPMENT CORPORATION* MAYNARD » MASS. 
ALL RIGHTS RESERVED 

THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED AND COPIED 
ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE AND WITH THE 
INCLUSION OF THE ABOME COPYRIGHT NOTICE. THIS SOFTWARE OR ANY OTHER 
COPIES THEREOF MAY NOT BE PRDUIDED OR OTHERWISE MADE AVAILABLE TO ANY 
OTHER PERSON. NO TITLE TO AND OWNERSHIP OF THE SOFTWARE IS HEREBY 
TRANSFERRED. 

THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE 
AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT 
CORPORATION, 

DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF ITS 
SOFTWARE ON EQUIPMENT THAT IS NOT SUPPLIED BY DIGITAL. 



RESERVED SYMBOL NAMES 



.VI and ...V5 are "Slobal" values defined in macros 

.VI -- controls .MCallinS of ...CM* and support of VI » V2 and 

V3 uersions of the expansions. 
,V5 -- controls feneration of .Audit information. 



.V* 



ire reserued for wore local and Slobal values 



,V2t ...V3» and ...V4 are in use currently {Y05.06) as 

local symbols (reusable in each macro definition). 



RESERVED MACRO NAMES 



. ,V1 . . 
. .VZ. . 
.MACS 
. . .CM* 



Error Messases 
?SYSMAC-W-Inual id argument* use *0 » not 



B-1 



General messasfe -- Macro a rSLuner, t s of "0" are almost always 
errorst (Which specify an address of 0. not a yalue of 0.) 

?SYSHAC-E-Odd or invalid yector specified 

.DRBEG & .DRMTB -- the 2 lower bits of the vector address must 
be . 

?SYSMAC-E-Ini,)alid control value - control 

.DRBOT -- an invalid controller type was specified. See definition 
of .DRBOT for valid type codes. 

?SYSMAC-E-Inval id s i d e s value - sides 

.DRBOT -- an invalid number of sides was specified* use 1 or 2. 
?SYSMAC-E-Primary boot too larSe 

.DREND -- the primary boot code overflowed the area available to it. 
?SYSMAC-E-M A L Must not be 0. UAL! 

.DRSET -- the second arSuwent to the macro must not be ft, if it 
is» the rest of the options in the table are ignored. 

7SYSMAC-E- In val i d parameter xi 

.DRSET -- the last argument must be blanK or one (or more) of 
the following; NOtNUM.OCT 

+ + 

. .yi. , 

.MCall the support routines and set the version to 1 

.MACRO ,.U1., 

.MCALL . ..CM0,..,CM1 ,. . .CM2t. ..CM3,. , .CM^.. . .CM5,. ..CMS... .CM7 

* ♦ ♦ V 1 = 1 

.ENDM 



. . .M2. . 

.MCall the support routines and set the version to 2 

.MACRO ,.V2.. 

.MCALL ...CM0,...CM1 ,, ..CM2,...CM3....CM/:i,...CM5,...CM6,...CM7 
* * ♦ y i =2 « 

.ENDM 

++ 

.MACS 

.MCall the support routines and set the version to C>=]3 

.MACRO .MACS 

.MCALL . . .CMC. . .CMl ,. ..CM2,. . .CM3,. . .CMa». ..CM5,.. .CMS,. , ,CM7 
. . . V 1 =3 . 

.ENDM 
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;++ 

; . . ,CMO 

! Moue a word to the stacK. If arSuwent blank or *tO 

! Put a on the stacK, If second argument present t 

; Generate an EMT with that value 

5 — 

.MACRO , . .CMO STARG»INS 
•IF B <STARG> 

CLR -(SP) 
, IFF 
.IF IDN <STARG>t«0 

CLR -(SP) 

• IFF 

.IIF IDN <STARG> <0> .ERROR i?SYSMAC- W- In u a 1 i d arSuwent. use *0 . not 0, 

MOM STARG»-(SP) 
.ENDC 
.ENDC 

.IIF NB <INS> EMT -o^ilNS;- 
.ENDM 

;++ 

5 ...CMl 

! Setup RO to point to AREA » set the CHAN and IC (subcode) 

! ualue in first word. This macro optimises number of 

; instructions to set up first word. 

; IC is f reed to decimal . 
5 - - 

.MACRO ...CMl AREA, IC»CHAN, FLAG. ARG»INS.CSET.BB 

...CMS <AREA> 

, . .M2 = 

.IF B <FLAG> 

,IIF B <AREA> . . . .M2=l 

.IFF 

.IIF DIF <FLAG>,SETt ...1.12=1 

.ENDC 

.IF NE . . .y2 

.IF IDN <CHAN>,<«0> 

CLRB SRO 
. IFF 

,IIF NB <CHAN> MOMB CHAN »@R0 
.ENDC 
.IFF 
.IF B <CHAN> 

MOMB «IC'. »1 (RO) 
.IFF 

•NTYPE .,.M2.CHAN 
. IF EO . . ,M2-'027 

MOM CHAN + < IC .*-OaOO> tSRO 

. IFF 

MOM «IC' .*'OilOO ,@R0 

MOMB CHAN.SRO 
,ENDC 
.ENDC 

.IIF IDN <CHAN> <0> .ERROR i ?SYSMAC-W- 1 n u al i d arsfument* use «0 , not 0, 

.,.CM2 <ARG> ,2 ,INS tCSET tBB 

.ENDM 

;++ 

i ...CM2 
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' Moue an arSurnent value to DFFSET(RO). 

j Use a CLR_ if the value is »0. 

I Offset is forced to decimali 

' BB is blank or B for b/te operations 

i If INS NB Senerate an EMT 375 

; — 

.MACRO ..,CM2 ARG,OFFSE.INS»CSET,BB 

.IF B <ARG> 

.IF NB <CSET> 

.IIF NE ...Ml-3. CLR'BB OFFSE'.(RO) 

.ENDC 

.IFF 

. IF ION <ARG> .»0 

CLR'BB OFFSE'.(RO) 
.IFF 

.IIF IDN <ARG> <0> .ERROR ;?SYSMAC-W- 1 n m a 1 i d arsuwent, use «0 , not o; 

MOV'BB ARG.OFFSE'. (RO) 
.ENDC 
.ENDC 

.IIF NB <INS> EMT "0375 
.ENDM 

;++ 

! . . ,CM3 
5 

i Move a channel and code to RO. 

i Follow this with an EMT 37^. 

' This waoro optimises the instructions used 

' to load RO. 



.MACRO 


...CM3 CHAN.IC 




.IF B <CHAN> 






MOV «IC*'0400 


.RO 


. IFF 






.NTYPE 


. . .V2.CHAN 




.IF EO 


. . .y2--'027 






MOV CHAN+<IC#' 


'0^00> .RO 


. IFF 








MOM »IC*'-0^00 


.RO 




BISB CHAN.RO 




.ENDC 






.ENDC 







EMT "0374 
.ENDM 

;++ 

1 ...CM4 
! 

! Setup for a SDAT/RCMD EMT block 



.MACRO ...CM4 AREA,BUF,WCNT,CRTN,IC(CODE 

.IIF IDN <CODE>.NOSET ...CMl < AREA > . I C , ,< CODE > 

.IIF DIF <CODE> .NOSET ...CMl < AREA > , IC .#0 ,<CODE > 

. . .CM2 <BUF> ,a 

. . .CM2 <WCNT> ,B 

. . .CM2 <CRTN> .B.E 

.ENDM 



;++ 



. . .CM5 
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i Moue a <byte) ualue to RO unless the src is 

? blank or RO. If sot then Generate nothing. 

; BB is blank for word operations or B for bvte. 

5 If second arSuwent present* generate an EMT with 

i that code value. 

5 - - 

.MACRO ...CMS SRC.INStBB 

. IF NB <SRC> 

.IIF DIF <SRC>.RO MDV'BB SRC .RO 

.ENDC 

.IIF NB <INS> EMT '■o<INS> 

,ENDM 

!+ + 

i ...CMB 

5 

5 Moue a code and channel to RO. This macro 

; optimises the instructions needed to load RO. 

i Do the f i rst . . .CM2 also. 

i IC and CHAN are forced to decimal. 

5 — 

.MACRO ...CMB AREA. IC, CHAN. FLAG. ARC. INS. CSET.BB 

,..CM5 <AREA> 

.IF B <FLAG> 

.IIF NB <AREA> MOy # IC ' . » "0400+CHAN ' . ,iRO 

!lIF IDN <FLAG>.SET MOM * IC ' . * " 0400 + CHAN ' . .@R0 

.ENDC 

,.,CM2 <ARG>.2 .INS.CSET.BB 

.ENDM 

;++ 

i ...CM7 

; Generate READ_/WRIT_ requests 

' — 

.MACRO ...CM7 AREA. CHAN .BUF.WCNT.BLK.CRTN.IC, CODE, Ul 

. IF EQ . , .yi-1 

...CMS <WCNT> 

...CMO <CRTN> 

...CMO <BUF> 

...CMO <CHAN>,<yi+AREA> 

.IFF 

, , .CMl < AREA >, I C,< CHAN >,< CODE > ,<BLK> 

. . .CM2 <BUF>,4 
. . .CM2 <WCNT> .G 
. . .CM2 <CRTN> ,8,E 
.ENDC 
.ENDM 

.MACRO .ABTIO CHAN 

.IF NDF . . .yi 

.MCALL .MACS 

.MACS 

.ENDC 

...CM3 <CHAN>,11, 

.ENDM 

!+ + 

! .AUDIT 

; macro to generate list of uersions starting at abs 110 
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' UP to 2B names 
5 

i First reference Generates a RadSO ualue for 110 of rel 



ease 



<=i>w,e»r»t>y,u,i,o»p,a.5»dtf,3,h.J,K»l,2,K,o.u,b,n. 



.MACRO .AUDIT 

.Save 

. Asect 

•I If NDF ...U5 ...y5=-ollO 

. = . . .ys 

•If EO .--^ollO 

. G 1 b 1 .Audit 
.List 

.NList 
.EndC 

'tT kir**^^ <'^>'>>>e,r,t,v,u,i .o.P.a.5,d.f .s.h.J.k.l ,z.x,c.u.b,n.r«> 
.IT NB < . . . U2.> 



M 



.Word , Audi t 



.List 



.Globl '...M2' 
.Word '...U2' 



.NList 

.EndC 

.EndR 

. . .y5=. 

.List 

.Word -1 
.NList 
.Restore 
.ENDM .AUDIT 

.MACRO .CDFN AREA »ADDR ,NUM .CODE 

.IF NDF . . .Ul 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMC <AREA> .13 .0 »<CODE> .<ADDR> 

...CM2 <NUM>.4.E 

.ENDM 

.MACRO .CHAIN 

MOM Jf 0^000. RO 

EMT -OSlii 
.ENDM 

.MACRO .CHCOP AREA, CHAN, OCHAN.JOBBLK .CODE 

. IF NDF . , .Ml 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMl <AREA> ,11 ,<CHAN> ,<CODE> ,<OCHAN> 

. IF NB <JOBBLK> 

...CM2 <JOBBLK>,fl,E 

.IFF 

. . .CM2 #0 ,4 ,E 

.ENDC 

.ENDM 

.MACRO .CLOSE CHAN 

.IF NDF . . ,yi 

.MCALL .MACS 

.MACS 

.ENDC 

.IF EO . . .Ml-1 

EMT -OaBO + CHAN;- 
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.IFF 

. . ,CM3 <CHAN> ,B, 

.ENDC 

.ENDM 



AREA ,IDtTIME = «0,CODE 



.MACRO .CMKT 

.IF NDF . . .Ml 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CM6 <AREA> »19»0 »<CODE> t<ID> 

...CM2 <TIME>.4.E.C 

.ENDM 

.MACRO .CNTXS AREA t ADDR »CODE 

.IF NDF . . ,U1 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMS <AREA> .27.0 .< CODE >.< ADDR > .E 

.ENDM 



.MACRO .CRAW AREA .ADDR .CODE 

. IF NDF . . .Ml 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMS <AREA>.30.2.<C0DE>.<ADDR> .E 

.ENDM 



.MACRO 


.CRRG AREA .ADDR .CODE 


.IF NDF 


...Ml 


.MCALL 


.MACS 


.MACS 




.ENDC 




. . . CMS 


<AREA> .30 .0 .<CODE> .<ADDR> .E 


.ENDM 




.MACRO 


.CSIGE DEMSPC.DEFEXT .CSTR 


.IF NDF 


...Ml 


.MCALL 


.MACS 


.MACS 




.ENDC 




.IF NB 


<LINBUF> 


. . .CMO 


<LINBUF> 


.NTYPE 


. , .M2 .DEMSPC 


.IF EC) 


. . .M2--^0Z7 


. . .CMO 


<DEMSPC'+1> 


. IFF 




. . .CMO 


<DEMSPC> 




INC (SP) 


.ENDC 




.IFF 




. . .CMO 


<DEMSPC> 


.ENDC 




. . .CMO 


<DEFEXT> 


. . . CMO 


<CSTRNG> .334 


.ENDM 





.MACRO .CSISP 

.IF NDF . . .Ml 

.MCALL .MACS 

.MACS 

.ENDC 

.IF NB <LINBUF> 

...CMO <LINBUF> 



OUTSPC .DEFEXT .CSTRNG .LINBUF 
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NTYPE ...U2tOUTSPC 

IF EO . , .yz-'oz? 

..CMO <0UTSPC'+1> 

IFF 

..CMC) <DUTSPC> 

INC (SP) 
ENDC 
IFF 

..CMO <OUTSPC> 
ENDC 

..CMO <DEFEXT> 
..CMO <CSTRNG> ,345 
ENDM 



.MACRO 


.CSTAT 


AREAfCHAN.ADDR 


,CODE 


.IF NDF 


. . .yi 






.MCALL 


.MACS 






.MACS 








.ENDC 








. . .CMl 


<AREA> 


,23 ,<CHAN> »<CODE> 


<ADDR> ,E 


.ENDM 








.MACRO 


.CTIMI 


TBK 






JSR 


R5 ,@$TIMIT 






.WORD 


TBK-. 






.WORD 


1 




.ENDM 








.MACRO 


.DATE 








MOM 


«"05000 ,R0 






EMT 


••0374 





.ENDM 

.MACRO .DELET AREA , CHAN ,DBLK ,SEONUM , CODE 

. IF NDF . , .Ml 

.MCALL .MACS 

.MACS 

.ENDC 

.IF EO . , .Ml-1 

...CMS <CHAN> ,<AREA> 

. IFF 

...CMS <AREA> 

.IF IDN <CHAN>,ttO 

CLR iRO 
. IFF 

.IIF IDN <CHAN> <0> .ERROR ! 7SYSMAC-W- Inu a 1 i d amiwent, use #0, not O; 

♦ * i y2= 

.IF B <CODE> 

. IIF B <AREA> , , , .M2=l 

.IFF 

.IIF DIF <CODE>,SET, .,.M2=1 

.ENDC 

.IF NE .. .M2 

.IIF NB <CHAN> MOMB CHAN »@R0 

.IFF 

. IF B <CHAN> 

CLRB URO) 
.IFF 

.NTYPE ..,M2#CHAN 
. IF EO . . .M2-"027 

MOM CHAN,@RO 
. IFF 

CLR @R0 

MOMB CHAN»@RO 
.ENDC 
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.ENDC 

,ENDC 

.ENDC 

.,.CH2 <DBLK>t2 

.,,CM2 <SEONUM> t4 .E tC 

.ENDC 

.ENDM 

.MACRO .DEVIC AREA >ADDR .L INK »CDDE 

.IF NDF . . .Ml 

.MCALL .MACS 

.MACS 

.ENDC 

.IF B LINK 

. . .CMS <AREA>.12 >0><CODE> »<ADDR> .E 

. IFF 

. . ,CMB <AREA> tlZ»l .< CODE > .< ADDR > »E 

.ENDC 

.ENDM 

.MACRO .DRAST NAME.PRI»ABT 
.GLOBL $INPTR 
.IF B <ABT> 

RETURN 
. IFF 

BR ABT 
.ENDC 
NAME'INT:! JSR R5t@$INPTR 

.WORD "C<PRI*'040>6:"0340 

.ENDM 

.MACRO .DRBEG NAME »MEC .DS IZ »DSTS .MTBL 

.ASECT 

!gLOBL NAME'ENDfNAME'INT 

•WORD <NAME'END-NAME'STRT> 



.IF B 


<DSIZ> 






.WORD 


NAME'DSIZE 


. IFF 








.WORD 


DSIZ 


.ENDC 






.IF B 


<DSTS> 






.WORD 


NAME'STS 


.IFF 








.WORD 


OSTS 


.ENDC 








.WORD 


"o<ERL*G+< 



■o<ERL*G+<MMG*T*Z>+<TIM*IT#4>+<RTE$M*10>> 

.="ol7G 

.IIF DF NAME'*CSR. .WORD NAME'$CSR 

.PSECT NAME'DMR 

NAME'STRT: : 

. IF NB '.'TBL 

.GLOBL UTBL 

.WORD <yTBL-. >/2.-l+'0100000 

.IFF 

.IF NB <MEC> .^, ^. 

.IIF NE MEC&3. .ERROR VEC ;?SYSMAC-E-Ddd or inualid ueotor specified, 

.WORD VEC&:"C3. 
.IFF 

.IF DF NAME'*MTB 
.GLOBL NAME'*UTB 

.WORD < NAME '*MTB-.>/Z.-l+" 01 00000 

• IFF 

.IIF NE NAME'$yEC&,3. .ERROR NAME'$MEC 5SYSMAC-E-0d d or invalid uector 

ispecifiedi 
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,ENDC 
.ENDC 
.ENDC 

NAME'SYS 
NAME'LOE 
NAME'COE 
.ENDM 



-WORD NAME'*yEC&X3, 



, WORD NAME' INT- , ,-0340 

.WORD 
.WORD 



.DRBOT 

CONTROL= is used to Generate the controller description bits 
in the boot block. The default yalue is correct for nearly 
all RT supported devices. As niany options may be specified as 
are supported by the boot code; 



<UBUS> 

<OBUS> 

<CBUS> 

<UMSCP> 

<OMSCP> 

<CMSCP> 

SIDES= 
floppy 
sidedness 



Unibus device 
Q-Bus device 
PC -Bus device 
Unibus MSCP device 
0-Bus MSCP device 
PC-Bus MSCP device 

is used to indicate the number of 
d values 
is not coded. 



sides supported in 
Hard media 



MACRO 



NOTE: the definition of a code does NOT imply any present 
or future product committment. 

, DRBOT NAME , ENTRY »READ » CONTRDL = < UBUS ,QBUS> ,SIDES = 1 
.DREND NAME 



TPS: 
TPB; 



.IIP NDF 
IIP NDF 
LF="ol2 
CR=^ol5 
B*BOOT='-olOOO 
B*DEMN="o471B 
B$DEyU=-^oa722 
B$READ= -04730 
. IF EQ 
B*DNAM= 
.IFF 
B*DNAM= 
.ENDC 
.ASECT 
.="oB2 



TPS = 
TPB = 



-01775B4 
^0177566 



MMG*T 
■R'NAME 

-R'NAME'X 



.PSECT 
NAME 



.WORD NAME 'BOOT, NAME 'BEND-NAME 'BOOT, READ-NAME 'BOOT 



BOOT: 
BR 
.y2='-ol00 



NAME 'BOOT 
NOP 



. IRP 

, , .V3: 

, IIF 
.IIF 
,IIF 
.IIF 

IIF 

IIF 

IIF 

. .V2 = 



IDN 
IDN 
IDN 
IDN 
IDN 
IDN 
EQ 

. .M2! . . .U3 



ENTRY-2. 

<contrdl; 

<X> 
<X> 
<X> 
<H> 
<X> 
<X> 



<UBUS> 

<OBUS> 

<CBUS> 

<OMSCP> 

<UMSCP> 

<CMSCP> 

.ERROR 



= 1 , 

= 2, 
= 4, 



. . .U3= 

. . .y3= 

. . .M3 = 

. . .y3=-oio 

. . .V3="o20 
. . .y3='-o40 
;?SYSMAC-E- 
icont rol i 



Invalid c 



n t r 1 value 
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,ENDR 

.=ENTRY-G. ,,^ ^^^ 

.BYTE "oZO,. . .VZ."o20.-^o"D<20+. . .UZ+20> 

.IF EQ <SIDES-1> 

BR ENTRY 
.IFF 

.IF EO <BIDES-2.> 



.IFF 

.ENDC 
.ENDC 
.ENDM 



BMI ENTRY 

.ERROR !?SYSMAC-E-Inual id sides value - sides! 



• MACRO .DRDEF NAME tCDDE .STAT .SIZE .CSR tMEC „^, „^ 

. MCALL . DRABT , , DRBEG . . DRBOT . . DREND , . DRF IN . . DRSET , . DRMTB . . FORK , . QELDF 

.IIF NDF RTE*M RTE$M=0 

.IIF NE RTE*M RTE*M=1 

.IIF NDF TIM*IT TIM$IT=0 

.IIF NE TIM*IT TIM$IT=1 

.IIF NDF MMG*T MMG*T=0 

,IIF NE MMG*T MMG$T=1 

.IIF NDF ERL*G ERL$G=0 

.IIF NE ERL*G ERL$G=1 

.IIF NE TIM$IT .MCALL . T IM I . . CT IM I 

.OELDF 

HDERR$=1 

EOF$=-' 20000 

yARSZ* = '-oaoo 

ABTIO$='-olOOO 

SPFUN*=' 02000 

HNDLR*='Q^OOO 

SPECL*="o 10000 

WONLY$=-o20000 

R0NLY$='o40000 

FILST$='-q100000 

NAME'DSIZ=SIZE 

NAME'$COD=CODE 

NAME'STS=<C0DE>!<STAT> 

.IIF NDF NAME'*CBR. NAME ' *CSR = CSR 

.IIF NDF NAME'*UECt NAME ' $MEC = VEC 

.GLOBL NAME '*CSR. NAME '*MEC 

.ENDM 

!++ 

! .DREND 

i FORCE is used to force the Seneration of the uector table 

! assi3riiri3 a ualue to FORCE causes the associated syssen 

; bit value to "forced" on for purposes of jfeneratinS the table. 

! F0RCE=1 will force feneration of the error lo3SinS vector 
! for instance. 

.MACRO .DREND NAME .FORCE = 

.PBECT NAME'DUR 

.IIF NDF NAME'$END. NAME'*END: 

.IF EQ .-NAME'*END 

NAME'$END! : 

. IF NE MMG$T!<F0RCE&:2. > 

*RLPTR! : .WORD O 

*MPPTR: : .WORD 

*GTBYT! : .WORD 

*PTBYT: : .WORD 

$PTWRD; ! .WORD 
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.ENDC 

.IIF NE ERL*G!<F0RCE&1> *ELPTR : : . WORD 

.IIF NE TIM$IT!<F0RCE&4.> «TIMI T : : , WORD 

SINPTR: : .WORD 

*FKPTR: : .WORD 

.GLOBL NAME'STRT 

NAME'END==. 

. IFF 

.PSECT NAME 'BOOT 

.IIF LT <NAME'B00T-. + -oGG4:>. .ERROR !?SYSMAC-E-P r ima ry boot too larSe! 

.=NAME'BOOT+'oBBi3 

BIOERR: JSR Rl , REPORT 

.WORD lOERR-NAME'BOOT 

REPORT: MOy «»BOOTF-NAME 'BOOT »R0 

JSR Rl ,REP 

MOV (Rl)RO 

JSR RlfREP 

MOM «CRLFLF-NAME'BOOT»RO 

JSR Rl ,REP 
RESET 
HALT 

BR .-2. 

REPORs MOVB (RO)+,@«TPB 

REP: TSTB @#TPS 

BPL REP 

TSTB iRO 

BNE REPOR 

RTS Rl 

BOOTF: .ASCIZ <CR><LF>"?BOOT-U- "< -■ oZOO> 

CRLFLFs .ASCIZ <CR><LF><LF> 

lOERR: .ASCIZ "I/O error" 

.EMEN 
NAME'BEND: ; 
.ENDC 
.ENDM 

.MACRO .DRFIN NAME 
.GLOBL NAME'COE 

MOV PC»R4 

ADD *NAME'COE-. ,R^ 



.ENDM 



MOV @«-054»R5 
JMP @~0270(R5) 



.MACRO .DRSET OPT ION .VAL ,RTN , MODE 

.ASECT 

. IF LE , --0 400 

.=-0400 

.IFF 

— o 
♦ - » - il » 

.ENDC 

. . .V2=0 

. IRP Xf<VAL> 

•^^no^" *;,;'^? *^^^ " '■^''' *^'"''"'°'"' i?SYSMAC-E-V A L Must not be 0, VAL? 
. . . vz.= . . . VZ+ 1 

.ENDR 

VAL 
. . .VZ=. 

.RAD50 \OPTION\ 
.=. , .VZ+4. 

.BYTE <RTN--o400>/Z. 
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. .uz = o 

IRP Xt<MODE> 

IF IDN iX> .<NUM> 

, ,y2=. 4 .UZ! -^olOO 

IFF 

IF IDN <X>»<NO> 

, ,y2=. . .U2! 'o200 

IFF 

IF IDN <X>f<OCT> 

, .V2=. . .'.'2! -0140 

IFF 

ERROR i?BYSMAC-E-Ii-ivalid parameter k! 

ENDC 
ENDC 
ENDC 
ENDR 



•BYTE ,..y2 
•WORD 



.ENDM 



.MACRO .DRMTB NAME .MEC > I NT » PS = 

. IF NB NAME 

NAME'*MTB! : 

. IFF 

.=.-2. 

.ENDC ,^. ,. 

.IIF NE UECftS. .ERROR MEC !?SYSMAC-E-Od d or invalid vector specifiedi 

.WORD MEC&,-C3. .INT-. ,'^o340! PS »0 
.ENDM 

.MACRO .DSTAT RETSPC .DNAM 

.IF NDF . . .VI 

.MCALL .MACS 

.MACS 

.ENDC 

...CMS <DNAM> 

...CMO <RETSPC>>342 

.ENDM 

.MACRO .ELAW AREA »ADDR »CODE 

. IF NDF . . .VI 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMS <AREA> (30 »3 t<CODE> t<ADDR> >E 

.ENDM 

.MACRO .ELRG AREA »ADDR .CODE 

. IF NDF , . .VI 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMS <AREA> >30 .1 .<CODE> .<ADDR> .E 

.ENDM 

.MACRO .ENTER AREA , CHAN .DBLK >LEN tSEONUM »CODE 

.IF NDF . . .VI 

.MCALL .MACS 

.MACS 

.ENDC 

.IF EO . . .Vl-1 

...CMS <CHAN> 

...CMO <DBLK> .<40 + AREA> 

. IFF 

. . .CMl < AREA > »2t< CHAN >.< CODE >t<DBLK> 

...CM2 <LEN>.4..C 
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...CM2 <SEC3NUM> »B »E .C 

.ENDC 

.ENDM 

.MACRO .EXIT 

EMT '0350 
.ENDM 

.MACRO .FETCH ADDR ,DNAM 

.IF NDF . , .VI 

.MCALL .MACS 

.MACS 

.ENDC 

...CMS <DNAM> 

...CMO <ADDR>,343 

.ENDM 

.MACRO .FORK FKBLK 

JSR R5.@$FKPTR 

.WORD FKBLK - . 
.ENDM 

.MACRO .FPROT AREA .CHAN »DBLK , PR0T = «1 .CODE 

. IF NDF . , ,yi 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMl <AREA> .35 »<CHAN> .<CODE> ,<DBLK> 

...CM2 <PROT> ,4 .E . .B 

.ENDM 

.MACRO .GMCX AREA ,ADDR »CODE 

.IF NDF . , .yi 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMS <AREA> .30 .B »<CODE> ,<ADDR> ,E 

.ENDM 

.MACRO .GTIM AREA .ADDR .CODE 

.IF NDF . . ,yi 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMS <AREA> ,17.0 ,<CODE> .<ADDR> .E 

.ENDM 

.MACRO .GTJB AREA .ADDR .JOBBLK .CODE 

. IF NDF , , .yi 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMS <AREA> .IB ,1 ,<CODE> ,<ADDR> 

. IF NB <JOBBLK> 

. IF IDN <JOBBLK> .<ME> 

. . .CM2 «-l ,a ,£ 

. IFF 

...CM2 <J0BBLK>,4.E 

.ENDC 

. IFF 

. . .CM2 «-3. iH ,E 

.ENDC 

.ENDM 

.MACRO .GTLIN L INBUF .PROMPT .TYPE 
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.IF NDF . , .Ml 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMO 

. IF 

. . .CMO 

.IFF 

. . .CMO 

.ENDC 

. . . CMO 

. . .CMO 

.ENDM 



<LINBUF> 

NB 

»3. 

*1 

<PROMPT> 
t345 



<TYPE> 



.MACRO .GMAL AREA »OFFSE »CODE 

.IF NDF . . .Ml 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMS <AREA>.Z8»0»<C0DE> t<OFFSE> tE 

.ENDM 



.MACRO .HERR 
MOM 
EMT 



.ENDM 

.MACRO 

.ENDM 



,HRESE 
EMT 



.MACRO .INTEN 
.IF B PIC 

JSR 
.IFF 

MOM 

JSR 
.ENDC 

.WORD 
.ENDM 

.MACRO .LOCK 

EMT 
.ENDM 



(t-^OZaOO »R0 
-0374 



■^0357 

PRIO (PIC 

R5 ,@'05a 

@*t-D54 t-<SP) 
R5»e(SP)+ 

'C<PRI0*32. >6:2Z4. 



•034B 



.MACRO .LOOKU 

.IF NDF . . .Ml 

.MCALL .MACS 

.MACS 

.ENDC 

. IF EQ 

. . .CM5 

.IFF 

. . .CMl 

. . .CM2 

.ENDC 

.ENDM 



AREA tCHAN »DBLK .SEQNUM »CDDE 



. . .Ml-1 
<CHAN>»<20+AREA> 

<AREA> »1 »<CHAN> ,<CODE> »<DBLK> 
<SEQNUM> ,ii »E»C 



.MACRO .MAP AREA tADDR .CODE 

. IF NDF . . .Ml 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMS <AREA> »30 t4»<C0DE> t<ADDR> »E 

.ENDM 
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.MACRO .MFPS ADDR 

MOy @«'D5i| t-(SP) 

ADD »-^03S2t(SP) 

CALL §(SP)+ 

•IIP NB <ADDR> MOMB (SP)+»ADOR 
.ENDM 

++ 

•MODULE 

Macro to define a standard identification for all 
modules. 

Inputs: 

Module 1-5 character s/itibol name (KEDIO) 

Release 3 char release identification (X05) 

Version 2 char uersion number (09) 

Comment n char title strin3 <I/0 Module> 

TITLE=YES Generate .Title (default) 

TITLE=NO do not Generate .Title 

IDENT=YES Senerate .Ident (default) 

IDENT=NO do not Generate .Ident 

AUDIT=NO venerate .Audit call (default) 

AUDIT=YES generate .Audit call 

LIB=NO generate .Audit global yalue (default) 
LIB=YES do not generate .Audit 

GLOBAL not specified (default) 

GLOBAL=gname substitutes gname for .'Module' 

Outputs: 

.Title 'Module' - 'Comment' title for module 

.Ident "'Release'. 'Version'" ident for module 

.'Module' ==: 'Uersion'. version value symbol Binary 

.Audit ==: "r'Release' release value symbol RadSO 

.MC all. Audit get. Audit definition 

.Audit .Audit .'Module' generate audit information 

definition of .NLCSI macro generate program ID string 

.NLCSI TYPE=»PART= 

TYPE=Z generate .AsoiZ (default) .AsciZ "KEDIO X05.09 " 

TYPE=I generate .Asoil .Ascil "KEDIO K05.09 " 

PART=ALL generate std ID (default) .Asoiz "KEDIO X05.09 " 

PART=NAME generate name .Asciz "KEDIO" 

PART=RLSUER generate release & version .Asciz "X05.09" 

PART=PREFIX generate message prefix .Asoiz "7KEDI0-" 

definition of .RModule macro generate RadSO for 'Module' 

.RModule 

.MACRO .MODULE Module Release Version Comment 

TITLE = YES .IDENT = YES .AUDIT = NO (GLOBAL »LIB = NO 
.MCall .Audit 
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.Ilf IDN <Title> <YES> .Title 'Module' - 'Comment' 

.Ilf IDN <Ident> <YES> .Ident " 'Re 1 ease ' , 'Me rs i on '" 

.Ilf IDN <Lib> <N0> . And i t = = ! '^ r 'Re 1 ease ' 

.If NB <GLQBAL> 

'Global ' = =: 'Version ' . 

,IIf IDN <Ai.idit> <YEB> .Audit 'Global' 

. IfF 

. 'Module' = =: 'Version'. 

.Ilf IDN <Audit> <YES> .Audit .'Module' 

.EndC 

.Macro .NLCSI TYPE=Z » PART=ALL 

.Ilf IDN <PART> <ALL> .Asci'Type' "'Module' ' Re 1 e as e ' . 'Me rs i on ' 

.Ilf IDN <PART> <NAME> .Asci'Type' "'Module' " 

.Ilf IDN <PART> <RLSMER> .Asci'Type' " ' Re 1 e as e ' . ' Me rs i on ' " 

.Ilf IDN <PART> <PREFIX> .Asci'Type' "?'Module'-" 

.EndM 

.Macro .RModule 

.RadSO " 'Module'" 
.EndM 

. . .M5=-oll0 
.ENDM 

.MACRO .MRKT AREA .T IME tCRTN , I D »CODE 

.IF NDF , . .Ml 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMS <AREA> tlB »0 .<CDDE> »<TIME> 

...CM2 <CRTN>»4 

...CM2 <ID>»B»E 

.ENDM 

.MACRO .MTATC AREA »ADDR .UNI T tCODE 

. IF NDF . . .Ml 

.MCALL .MACS 

• MACS 

.ENDC 

. . .CMS <AREA> *31 »5 .<CODE> t<ADDR> 

...CM2 <UNIT> .4 .E » »B 

.ENDM 

.MACRO .MTDTC AREA .UN I T tCOOE 

. IF NDF . , .Ml 

.MCALL .MACS 

.MACS 

.ENDC 

...CMS <AREA> .31 tB .<CODE> 

,..CM2 <UNIT> .4 .E . .B 

.ENDM 

.MACRO .MTGET AREA .ADDR .UN IT .CODE 

.IF NDF . . .Ml 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMS <AREA> .31 .1 .<CDDE> .<ADDR> 

...CM2 <UNIT> .4 .E . .B 

.ENDM 

.MACRO .MTIN AREA .ADDR .UN IT .CHRCNT .CODE 

. IF NDF . . .Ml 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMS <AREA> .31 .2 .<CODE> ,<ADDR> 
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...CM2 <UNIT>,il» » .B 
...CMS <CHRCNT>»5.Et tB 
.ENDM 

.MACRO .MTOUT AREA . ADDR tUNIT tCHRCNT »CODE 

. IF NDF . . .yi 

.MCALL .MACS 

.MACS 

.ENDC 

...CM6 <AREA> »31 »3 »<CODE> »<ADDR> 

...CM2 <UNIT>tat»»B 

...CM2 <CHRCNT> .5 »E , >B 

.ENDM 

.MACRO .MTPRN AREA .ADDR .UNIT tCODE 

.IF NDF , . .VI 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMS <AREA> ,31 ,7 ,<CODE> ,<ADDR> 

...CM2 <UNIT> ,4 ,E, ,B 

.ENDM 

.MACRO .MIPS ADDR 

.IIF NB <ADDR> CLR -(SP) 

,IIF NB <ADDR> MOVE ADDR,(SP) 

MOM @#-054,-(SP) 

ADD #'03B0>(SP) 

CALL @(SP)+ 
.ENDM 

MACRO .MTRCT AREA , UN IT , CODE 

IF NDF . . .VI 

MCALL .MACS 

MACS 

ENDC 

. .CMS <AREA> t31 ,U »<CODE> 

..CM2 <UNIT> ,a ,E , ,B 

ENDM 

AREA ,ADDf? .UNIT .CODE 



MACRO 


.MTSET 


IF NDF 


. . .VI 


MCALL 


.MACS 


MACS 




ENDC 




. .CMS 


<AREA 


. .CM2 


<UNIT 


ENDM 





<AREA> ,31.0 ,<CODE> .<ADDR> 
4 .E . .B 



MACRO .MTSTA AREA , ADDR .CODE 
IF NDF . . .VI 



.MCALL 


.MACS 


.MACS 




.ENDC 




. . .CMS 


<AREA> ,31 ,8 ,<CODE> ,<ADDR:; 


. . .CM2 


• , 4 . E 


.ENDM 




.MACRO 


.MWAIT 




MOV *t-04400.RO 




EMT "0374 



.ENDM 

• MACRO .PEEK AREA .ADDR .CODE 
. IF NDF . . .VI 
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.MCALL 


.MACS 




.MACS 






.ENDC 






. . .CMS 


<AREA> 


»ZS»1 t<CODE> t<ADDR>.E 


.ENDM 






.MACRO 


.POKE 


AREA »AODR.MALUE ,COD 


.IF NDF 


...Ml 




.MCALL 


.MACS 




.MACS 






.ENDC 






. . . CMS 


<AREA> 


t28 .3»<C0DE> »<ADDR> 


, . .CM2 


<MALUE> ,a ,E 


.ENDM 






.MACRO 


.PRINT 


ADDR 


.IF NDF 


, . .Ml 




.MCALL 


.MACS 




.MACS 






.ENDC 






. . ,CM5 


<ADDR> 


(351 


.ENDM 






.MACRO 


. PROTE 


AREA»ADDR»CODE 


.IF NDF 


. . .Ml 




.MCALL 


.MACS 




.MACS 






.ENDC 






. . . CMS 


<AREA> 


»25»0 »<CODE> .<ADDR> ,E 


.ENDM 






.MACRO 


.PURGE 


CHAN 


.IF NDF 


. . ,M1 




.MCALL 


.MACS 




.MACS 






.ENDC 






. . . CMS 


<CHAN> 


,3, 


.ENDM 







.MACRO .PMAL AREA tOFFSE .MALUE tCODE 

. IF NDF . . .Ml 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMS <AREA> .2B »2 »< CODE > »< 0FFSE:> 

,..CM2 <MALUE>»a»E 

.ENDM 

.MACRO .QELDF 

.IIF NDF MMG$T> MMG*T=1 

.IIF NE MMG$T , MMG*T=1 

O.LINK=0 

Q.CSW=2. 

O.BLKN=4. 

O.FUNC=B. 

0. JNUM=7, 

Q.UNIT=7. 

Q.BUFF=-010 

Q.WCNT='012 

Q.C0MP=-^014 

. IRP X »<LINK »CSWtBLKN .FUNC .JNUM.UNIT tBUFF tWCNT »COMP> 

Q$'X = 0. "X-H 

.ENDR 

. IF EO MMG$T 

Q,ELGH=*01B 
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.IFF 

O.PAR='-016 

0$PAR=-'012 

O.ELGH=-02'a 

.ENDC 

.ENDM 

.MACRO .QSET ADDR *LEN 

. IF NDF . , .Ul 

.MCALL .MACS 

.MACS 

.ENDC 

...CMS <LEN> 

...CMO <ADDR>,353 

.ENDM 

.MACRO .RCTRL 

EMT '0355 
.ENDM 

.MACRO .RCUD AREA .BUF »WCNT ,CRTN = »1 .CODE 

. IF NDF . . ,yi 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CM^ <AREA> .<BUF> (<WCNT> .<CRTN> .22 t<CODE> 

.ENDM 

.MACRO .RC^DC AREA .BUF .WCNT ,CRTN .CODE 

.IF NDF , . .Ml 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMa <AREA> .<BUF> .<WCNT> .<CRTN> .22 ,<CODE> 

.ENDM 

.MACRO .RCMDW AREA .BUF .WCNT .CRTN = »0 .CODE 

. IF NDF . . .VI 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CM4 <AREA> .<BUF> ,<WCNT> t<CRTN> .22 ,<CODE> 

.ENDM 

.MACRO .RDBBK RGSIZ 
.MCALL .RDBDF 
.RDBDF 

.WORD 

.WORD RGSIZ 

.WORD 
.ENDM 

.MACRO .RDBDF 

R.GID=0 

R.GSI2=2. 

R.GSTS=a. 

R.GLGH=B. 

RS.CRR=*^0100000 

RS.UNM="040000 

RS.NAL="020000 

.ENDM 

.MACRO .READ AREA .CHAN .BUF »WCNT .BLK .CRTN = « 1 .CODE 
. IF NDF . . . VI 
.MCALL .MACS 
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• MACS 

• ENDC 

. . ,CM7 <AREA> .<CHAN> ,<BUF> .<WCNT> »<BLK> t<CRTN> »B »<CODE> »200 
.ENDM 

.MACRO .READC AREA tCHAN tBUF tWCNT »CRTN tBLK »CODE 

. IF NDF . . .Ml 

.MCALL .MACS 

.MACS 

.ENDC 

...CM7 <AREA>»<CHAN>t<BUF>t<WCNT>»<BLK>(<CRTN>t8»<C0DE>t200 

.ENDM 

.MACRO .READW AREA »CHAN »BUF »WCNT .BLK ,CRTN = #0 .CODE 

.IF NDF . . .Ml 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CM7 <AREA>»<CHAN> ,< BUF > .< WCNT > .< BLK > >< CRTN > .8.<C0DE> .200 

.ENDM 

.MACRO .REGDEF 
.ENDM 

.MACRO .RELEA DNAM 

. IF NDF . . .Ml 

.MCALL .MACS 

.MACS 

.ENDC 

...CM5 <DNAM> 

...CMO .343 

.ENDM 

.MACRO .RENAM AREA .CHAN .DBLK .CODE 

. IF NDF . . .Ml 

.MCALL .MACS 

.MACS 

.ENDC 

.IF EO . . .Ml-1 

...CM5 <CHAN> .<100 + AREA> 

, IFF 

, . .CMl <AREA> .4 .<CHAN> .<CODE> .<DBLK> .E 

.ENDC 

.ENDM 

• MACRO .REOPE AREA .CHAN .CBLK .CODE 
, IF NDF . . .Ml 

.MCALL .MACS 

.MACS 

.ENDC 

.IF EO . . .Ml-1 

...CMS <CHAN> .<140+AREA> 

. IFF 

. . .CMl <AREA> .6 .<CHAN> .<CODE> .<CBLK> .E 

.ENDC 

.ENDM 

.MACRO .RSUM 

MOM (t'OlOOO .RO 

EMT -0374 
.ENDM 

.MACRO .SAMES AREA .CHAN .CBLK .CODE 
.IF NDF . . .Ml 
.MCALL .MACS 
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.MACS 

.ENDC 

.IF EO , . .yi-1 

...CMS <CHAN>,<120+AREA> 

, IFF 

. . .CM! <AREA>.5.<CHAN>t<CQDE> »<CBLK>.E 

.ENDC 

.ENDM 

.MACRO .BCCA AREA »ADDR i CODE 

.IF NDF . . .Ul 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMS < AREA >»2S,0.< CODE >»<AODR>.E 

.ENDM 

.MACRO ,SDAT AREA .BUF tWCNT ,CRTN = * 1 , CODE 

.IF NDF . . .yi 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CM4 <AREA> .<BUF>.<WCNT> t<CRTN> »21 »<CODE> 

.ENDM 

.MACRO .SDATC AREA tBUF >WCNT f CRTN tCODE 

, IF NDF . . ,U1 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CM4 <AREA>.<BUF> j<WCNT> ><CRTN> .21 ,<CODE> 

.ENDM 

.MACRO .SDATW AREA »BUF .WCNT ,CRTN = «0 »CODE 

.IF NDF . . .Ml 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CM4 <AREA> »<BUF> .<WCNT> .<CRTN> ,21 .<CODE> 

.ENDM 

.MACRO .SDTTM AREA ,ADDR , CODE 

.IF NDF . . .Ul 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMS <AREA> ,32 ,0 ,<CODE> ,<ADDR> ,E 

.ENDM 

.MACRO .SERR 

MOM #-02000, RO 

EMT '037^ 
.ENDM 

.MACRO .SETTO ADDR 

.IF NDF , . .Ml 

.MCALL .MACS 

.MACS 

.ENDC 

...CMS <ADDR>,35a 

.ENDM 

.MACRO .SFDAT AREA , CHAN ,DBLK ,DATE = #0 .CODE 
. IF NDF , . .Ml 
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.MCALL .MACS 

.MACS 

.ENDC 

. . .CMl <AREA> ,3a »<CHAN> .<CDDE> »<DBLK> 

...CMZ <DATE>f4fE 

.ENDM 

.MACRO .SFPA AREA»ADDR jCDDE 

.IF NDF . . ,i.'l 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMS < AREA > (24 »0»<CODE> »<ADDR> tE 

.ENDM 

.MACRO .SPCPS AREA. ADDR. CODE 

.IF NDF . . .Ml 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMS <AREA> (33 .0 f<CODE> »<ADDR> »E 

.ENDM 

.MACRO .SPFUN AREA tCHAN . FUNC .BUF .WCNT tBLK »CRTN = «0 tCODE 

. IF NDF . . .yi 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMl <AREA> .2B»<CHAN> ><CDDE> ,<BLK> 

..,CM2 <BUF>t4 

...CMZ <WCNT>.G 

.IF NB FUNC 

.NTYPE ...V2.FUNC 

.IF NE . . ,y2--'D27 

.IIF DIF <CODE> .NOSET .. . .CM2 « -0377 .8 . . .B 

...CMZ <FUNC>t9...B 

. IFF 

...CM2 <FUNC'#-^04000377> .8 

.ENDC 

.ENDC 

...CMZ <CRTN> .lO.E .C 

.ENDM 

.MACRO .SPND 

MOU «-0400.R0 

EMT -^0374 
.ENDM 

.MACRO .SRESE 

EMT "035Z 
.ENDM 

.MACRO .SYNCH AREA. PIC 

. IF B PIC 

.IIF NB <AREA> MOM AREA .R4 

. IFF 

.IF NB AREA 

MOM PC.R4 

ADD «AREA-. tPOi 
.ENDC 
.ENDC 

MOM @«'-054tR5 

JSR R5 .@-0324(R5) 
.ENDM 
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.MACRO .TIMIO T5K»HI,L0 

JSR R5f@$TIMIT 

.WORD TBK-. 

.WORD 



.WORD HI 
.WORD LO 



.ENDM 



.MACRO .TLDCK 

MOU «"03fl00.R0 

EMT "0374 
.ENDM 

.MACRO .TRPSE AREA » ADDR >C0DE 

. IF NDF . . .yi 

.MCALL .MACS 

.MACS 

.ENDC 

. , .CMG <AREA>»3 tO t<CODE> .<ADDR> .E 

.ENDM 

.MACRO .TTINR 

EMT -0340 
.ENDM 

.MACRO .TTDUT 

EMT -0341 
.ENDM 

.MACRO .TTYIN CHAR 

EMT "0340 

BCS .-2. 
. IF NB <CHAR> 

.IIF DIF <CHAR>,RO MDUB ROjCHAR 
.ENDC 
.ENDM 

.MACRO .TTYOU CHAR 
. IF NDF . . .yi 
.MCALL .MACS 
.MACS 
.ENDC 

. . .CMS <CHAR> .341 .B 
BCS .-2. 
.ENDM 

.MACRO .TWAIT AREA .T IME .CODE 

.IF NDF . . ,V1 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMS <AREA> .20 .0 .<CODE> .<TIME> .E 

.ENDM 

.MACRO .UNLOC 

EMT -0347 
.ENDM 

.MACRO .UNMAP AREA .ADDR .CODE 

. IF NDF . . .yi 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMS <AREA> ,30 .5 ,<CODE> .<ADDR> lE 

.ENDM 
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.MACRO .UNPRO AREA t ADDR >CODE 

.IF NDF . . .Ml 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CMS <AREA> t25 ,1 »<CODE> .<ADDR> (E 

.ENDM 

.MACRO .WAIT CHAN 

. IF NDF , . .yi 

.MCALL .MACS 

.MACS 

.ENDC 

.IF EQ . . .Vl-1 

EMT ■•■0<240+CHAN> 
. IFF 
. IF B <CHAN> 

CLR RO 
. IFF 

.NTYPE .,.M2.CHAN 
.IF EO , . .M2-"027 
. IF IDN <CHAN> ,nO 

CLR RO 
.IFF 
.IIF IDN <CHAN> <0:> .ERROR i ?SYSMAC-W- 1 nu a 1 i d arSument* use »0 t not 05 

MOM CHANtRO 
.ENDC 
. IFF 

CLR RO 

BISB CHANtRO 
.ENDC 
.ENDC 



EMT "0374 



.ENDC 
.ENDM 



.MACRO .WDBBK WNAPR »WNS I Z .WNR ID .WNOFF tWNLEN tWNSTS 
•MCALL .WDBDF 



.WDBDF 


.BYTE 






.BYTE 


WNAPR 




.WORD 






.WORD 


WNSIZ 




.WORD 


WNRID 




.WORD 


WNOFF 




.WORD 


WNLEN 




.WORD 


WNSTS 


.ENDM 






.MACRO 


.WDBDF 




W.NID=0 






W.NAPR= 


1 




W.NBAS = 


2. 




W.NSIZ= 


4. 




W.NRID= 


6. 




W.NOFF= 


"010 




W,NLEN= 


"012 




W.NSTS= 


"014 




W.NLGH= 


"OIB 




WS.CRW= 


"0100000 




WS.UNM= 


"040000 




WS.ELW= 


"020000 




WS,MAP= 


"0400 




.ENDM 
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.MACRO .WRITC AREA .CHAN >BUF ,WCNT .CRTN .BLK .CODE 

.IF NDF , . .yi 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CM7 <AREA> .<CHAN:> .<BUF> .<WCNT> .< BLK > ,< CRTN > .9 .<CODE> .220 
.ENDM 

.MACRO .WRITE AREA .CHAN .BUF ,WCNT .BLK ,CRTN = « 1 .CODE 

.IF NDF . . .Ml 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CM7 < AREA >.< CHAN >.< BUF >.<WCNT>.< BLK > .< CRTN> ,9 .<CODE > .220 
.ENDM 

.MACRO .WRITW AREA .CHAN .BUF .WCNT .BLK ,CRTN = «0 .CODE 

.IF NDF . , .Ml 

.MCALL .MACS 

.MACS 

.ENDC 

. . .CM7 <AREA> .< CHAN >.< BUF > .< WCNT > ,< BLK > .< CRTN> .9 .< CODE> .220 
.ENDM 
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relationship to .CHAIN, 2-5 

relationship to .SRESET, 2-132 

restrictions, 1-26 



summary, 1-32 

using, 1-16 
.CHAIN programmed request, 2-4 

summary, 1-32 

using, 1-24 
CHAIN system subroutine, 3-1 

summary, 1-64 
Channel allocation 

using .CDFN, 1-16 
Channel numbers 

description, 1-11 

system subroutine library, 1-39 
Channel status word 

See CSW 
Character strings 

allocating in FORTRAN, 1-59 

passing to subprograms, 1-60 

quoted literals, 1-61 

support in SYSLIB, 1-57 
.CHCOPY programmed request, 2-6 

summary, 1-36 

using, 1-23 

Version 4, 1-29 
.CLEAR graphics macro, A-4 
CLOSEC system subroutine, 3-2 

relationship to ICSI, 3-16 

relationshp to lENTER, 3-21 

summary, 1-61 

USR requirements, 1-42 
CLOSE keyboard command 

after .EXIT, 1-24 

relationship to .EXIT, 2-43 
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.CLOSE programmed request, 2-8 
not done by .CSISPC, 2-21 
on a protected file, 2-49 
relationship to .CHCOPY, 2-6 
relationship to .ENTER, 2-42 
relationship to .LOOKUP, 2-65 
relationship to .PURGE, 2-90 
relationship to .SERR, 2-59 
requires device handler, 2-45 
summary, 1-32 
using, 1-19, 1-24 
.CMKT programmed request, 2-9 
relationship to .MRKT, 2-71 
summary, 1-32 
using, 1-24 
.CNTXSW programmed request, 2-10 
restrictions, 1-26 
summary, 1-36 
using, 1-16 
Command String Interpreter 

See CSI 
Completion routines 
introduction, 1-21 
restrictions, 1-22, 1-40, 2-2 
system subroutine library, 1-39 
CONCAT system subroutine, 3-4 

summary, 1-58, 1-66 
.CRAW programmed request, 2-12 
relationship to .GMCX, 2-50 
summary, 1-36 
using, 1-26 
.CRRG programmed request, 2-15 
summary, 1-36 
using, 1-26 
CSI 
imphcit .UNLOCK, 2-63 
introduction, 1-18 
options, 2-19 
using, 2-16 
.CSIGEN programmed request, 2-16 
compared to .GTLIN, 2-55 
implicit .UNLOCK, 2-63 
relationship to .LOOKUP, 2-65 
summary, 1-32 
using, 1-18 
.CSISPC programmed request, 2-21 
compared to .GTLIN, 2-55 
implicit .UNLOCK, 2-63 
relationship to .SETTOP and USR, 

2-119 
summary, 1-32 
using, 1-19 
CSI special mode 
See .CSISPC 



.CSTAT programmed request, 2-24 

summary, 1-32 

Version 5, 1-29 
.CSTATUS programmed request 

using, 1-18 
CSW 

bits defined by .DRDEF, 2-34 
•CTIMIO macro, 2-25 

expansion, 2-26 

relationship to .DRDEF, 2-33 

summary, 1-32 
CTRL/C 

disabling, 2-112 
CTRL/0 

reset by .RCTRLO, 2-95 
CVTTIM system subroutine, 3-5 

instead of .GTIM, 2-52 

summary, 1-64 

using, 1-56 

Date 

.GTIM required for date rollover, 
2-52 

internal format, 2-26 

month and year rollover, 2-26 

set by .SDTTM, 2-117 
.DATE programmed request, 2-26 

summary, 1-32 

using, 1-18 
DATE subroutine (in FORLIB) 

using, 1-56 
.DELETE programmed request, 2-27 

on a protected file, 2-49 

requires device handler, 2-45 

summary, 1-32 

using, 1-19 
Device blocks 

description, 1-12 

with system subroutine library, 1-41 
Device handler macros 

.CTIMIO, 2-25 

.DRAST, 2-30 

.DRBEG, 2-32 

.DRBOT, 2-32 

.DREND, 2-34 

.DRFIN, 2-35 

.DRSET, 2-35 

.DRVTB, 2-36 

.FORK, 2-47 

.INTEN, 2-61 

.SYNCH, 2-132 

.TIMIO, 2-135 
Device handlers 

writing, 1-27 
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Device identification codes 

list of values, 2-37 
.DEVICE programmed request, 2-28 

summary, 1-36 

using, 1-17 
Device status word 

contents, 2-37 

defined by .DRDEF, 2-33 
DEVICE system subroutine, 3-5 

relationship to INTSET, 3-29 

summary, 1-64 
DHALT display halt instruction, A-14 
Display file handler 

assembling graphics programs, A-16 

assembly instructions, A-24 

description, A-1 

example, A— 27 

linking, A-16 

linking graphics programs, A-16 

subroutine summary, A-21 

using, A-15 
Display file structure, A-17 

BASIC-11 graphics software, A-20 

subroutine calls, A-18 
Display processor mnemonics, A-23 
DJFLT system subroutine, 3-6 

summary, 1—65 

using, 1-57 
DJSR subroutine call instruction, A-13 
DNAME load name register instruction, 

A-14 
.DRAST macro, 2-30 

relationship to .DRDEF, 2-33 

relationship to .FORK, 2-48 

summary, 1-32 

using, 1-27 
.DRBEG macro, 2-32 

relationship to .DRDEF, 2-33 

relationship to .DRVTB, 2-36 

relationship to .FORK, 2-48 

summary, 1-32 

using, 1-27 
•DRBOT macro, 2-32 

relationship to .DRDEF, 2-33 

summary, 1-32 

using, 1-27 
.DRDEF macro, 2-33 

summary, 1-33 

use before .DRBEG, 2-32 

using, 1-27 
.DREND macro, 2-34 

called by .DRBOT, 2-32 

relationship to .DRDEF, 2-33 

relationship to .DRVTB, 2-36 



relationship to .FORK, 2-48 

summary, 1-33 

using, 1-27 
DRET subroutine return instruction, 

A-13 
.DRFIN macro, 2-35 

relationship to .DRDEF, 2-33 

relationship to .FORK, 2-48 

summary, 1-33 

using, 1-27 
.DRSET macro, 2-35 

relationship to .DRDEF, 2-33 

summary, 1-33 

using, 1-27 
.DRVTB macro, 2-36 

relationship to .DRDEF, 2-33 

summary, 1-33 

using, 1-27 
DSTAT display status instruction, A-14 
.DSTATUS programmed request, 2-36 

relationship to .SETTOP and USR, 
2-119 

summary, 1-33 

using, 1-18 

.ELAW programmed request, 2-39 
relationship to .CRAW, 2-13 
summary, 1-36 
using, 1-26 

$ELPTR 
defined by .DREND, 2-34 

.ELRG, 2-15 

.ELRG programmed request, 2-40 
summary, 1-36 
using, 1-26 

EMT codes 

See also Programmed requests 

EMT 374, 1-7 

EMT 375, 1-8 

meaning of different values, 1-3 

EMT instructions 

See Programmed requests 

.ENTER programmed request, 2-40 
done by .CSIGEN, 2-16 
not done by .CSISPC, 2-21 
on a protected file, 2-49 
relationship to .CHCOPY, 2-7 
relationship to .CLOSE, 2-8 
relationship to .CSTAT, 2-24 
relationship to .READx, 2-100 
relationship to .SAVESTATUS, 2-110 
relationship to .SERR, 2-59 
relationship to .SRESET, 2-131 
relationship to .WRITx, 2-149 
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requires device handler, 2-45 

summary, 1-33 

using, 1-19 
EOF$ 

defined by .DRDEF, 2-34 
ERL$G 

defined by .DRDEF, 2-33 
$ERLOG pointer 

in handler termination table, 2-34 
Error processing 

monitor errors, 1-17 
Errors 

intercepting monitor errors, 2-137 

programmed requests, 1-12 
.EXIT programmed request, 2-43 

relationship to .DEVICE, 2-28 

summary, 1-33 

using, 1-24 
Extended memory monitor 

See XM monitor 



FB monitor 

foreground job and .FETCH, 2-45 

introduction, 1-2 
.FETCH programmed request, 2-45 

done by .CSIGEN, 2-16 

fills in $FKPTR, 2-48 

not done by .CSISPC, 2-21 

relationship to $INPTR, 2-30 

relationship to .ENTER, 2-42 

relationship to .SETTOP and USR, 
2-119 

relationship to .SRESET, 2-131 

relationship to handler termination 
table, 2-35 

summary, 1-33 

Version 5, 1-29 
File operations 

introduction, 1-19 
FILST$ 

defined by .DRDEF, 2-33 
$FKPTR 

defined by .DREND, 2-34 

setup by user program, 2-49 
Foreground/background 

communications, 1-23 

context switch, 1-23 

with FORTRAN programs, 1-52 
Foreground/background monitor 

See FB monitor 
.FORK macro, 2-47 

relationship to .DRDEF, 2-33 

summary, 1-33 



$FORK pointer 

in handler termination table, 2-34 
FORLIB.OBJ 

linking, 1-55 
FORTRAN logical units 

relationship to .CHAIN, 2-5 
FORTRAN programs 

calculating workspace, 1-53 
.FPROT programmed request, 2-49 

relationship to .RENAME, 2-108 

requires device handler, 2-45 

summary, 1-33 

using, 1-20 

General mode 

See .CSIGEN 
$GETBYT pointer 

in handler termination table, 2-34 
GETSTR system subroutine, 3-7 

summary, 1-58, 1-66 

USR requirements, 1-42 
.GMCX programmed request, 2-50 

summary, 1-37 

using, 1-26 
Graphics macro calls 

summary, A-21 
$GTBYT 

defined by .DREND, 2-34 
.GTIM programmed request, 2-51 

summary, 1-33 

using, 1-18 
GTIM system subroutine, 3-7 

summary, 1-64 
.GTJB programmed request, 2-53 

summary, 1-33 

using, 1-18 

Version 4, 1-29 
GTJB system subroutine, 3-8 

summary, 1-64 
.GTLIN programmed request, 2-55 

implicit .UNLOCK, 2-63 

relationship to .SETTOP and USR, 
2-119 

summary, 1-33 

using, 1-19 

Version 5, 1-29 
GTLIN system subroutine, 3-9 

summary, 1-62 

USR requirements, 1-42 
GT OFF keyboard command, A-2 
GT ON keyboard command, A-2 
.GVAL programmed request, 2-57 

compared with .PEEK, 2-86 

summary, 1-33 
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HDERR$ 

defined by .DRDEF, 2-34 
.HERR programmed request, 2-58 

summary, 1-33 

using, 1-17 
HNDLR$ 

defined by .DRDEF, 2-33 
.HRESET programmed request, 2-61 

relationship to .CDFN, 2-3 

relationship to .LOOKUP, 2-65 

relationship to .PURGE, 2-90 

relationship to .QSET, 2-93 

summary, 1-33 

using, 1-24 



I/O operations 

introduction, 1-20 
lABTIO system subroutine, 3-10 

summary, 1-62 
lADDR system subroutine, 3-10 

summary, 1-67 
lAJFLT system subroutine, 3-11 

summary, 1-65 

using, 1-57 
lASIGN system subroutine, 3-11 

summary, 1-63 
ICDFN system subroutine, 3-13 

summary, 1-63 

USR requirements, 1-42 
ICHCPY system subroutine, 3-14 

summary, 1-63 
ICLOSE system subroutine, 3-2 

relationship to lENTER, 3-21 

summary, 1-61 

USR requirements, 1-42 
ICMKT system subroutine, 3-15 

cancelling an ITIMER request, 3-56 

cancelling ISCHED requests, 3-44 

summary, 1-64 
ICSI system subroutine, 3-16 

summary, 1-63 

using argument from IFETCH, 3-23 

using with lASIGN, 3-11 

USR requirements, 1-42 
ICSTAT system subroutine, 3-18 

summary, 1-63 
IDATE subroutine (in FORLIB) 

using, 1-56 
IDELET system subroutine, 3-18 

summary, 1-61 

USR requirements, 1-42 
IDJFLT system subroutine, 3-20 

summary, 1-65 

using, 1-57 



IDSTAT system subroutine, 3-20 

summary, 1—64 

USR requirements, 1-42 
•lENTER system subroutine, 3-21 

relationship to CLOSE, 3-3 

relationship to ICSI, 3-16 

summary, 1-61 

USR requirements, 1—42 
IFETCH system subroutine, 3-23 

relationship to ICSI, 3-16 

relationship to IDELET, 3-19 

summary, 1-65 

USR requirements, 1-42 
IFPROT system subroutine, 3-23 

summary, 1-61 
IFREEC system subroutine, 3-24 

summary, 1-63 
IGETC system subroutine, 3-24 

summary, 1—63 
IGETSP system subroutine, 3-25 

summary, 1-67 
IGTJB system subroutine, 3-8 

summary, 1-64 
IJCVT system subroutine, 3-26 

summary, 1-65 

using, 1-57 
ILUN system subroutine, 3-26 

summary, 1-63 
INDEX system subroutine, 3-27 

summary, 1-58, 1-66 
Indirect command files 

relationship to .CSIGEN, 2-17 
$INPTR 

defined by .DREND, 2-34 

referenced by .DRAST, 2-30 
Input/output operations 

See I/O operations 
INSERT system subroutine, 3-27 

summary, 1-58, 1-66 
•INSRT graphics macro, A-5 
INTEGER*4 support 

in SYSLIB, 1-56 
.INTEN macro, 2-61 

must precede .FORK, 2-48 

relationship to .SPND/.RSUM, 2-130 

summary, 1-33 

using, 1-26 
$INTEN monitor routine 

referenced by .DRAST, 2-30 
$INTEN pointer 

in handler termination table, 2-34 
Interrupt service routines, 1-26 

use of .SYNCH, 2-132 
INTSET system subroutine, 3-28 

summary, 1-67 



Index-5 



IPEEKB system subroutine, 3--30 

restrictions, 1-45 

summary, 1-67 
IPEEK system subroutine, 3-30 

restrictions, 1-45 

summary, 1-67 

using with IGETSP, 3-25 
IPOKEB system subroutine, 3-31 

restrictions, 1-45 

summary, 1-67 
IPOKE system subroutine, 3-31 

restrictions, 1-45 

summary, 1-67 

using with IGETSP, 3-25 
IPUT system subroutine, 3-32 

summary, 1-67 
IQSET system subroutine, 3-32 

summary, 1-65 

using, 1-45 

USR requirements, 1-42 
IRAD50 system subroutine, 3-33 

summary, 1-67 

using, 1-57 
IRCVDC system subroutine, 3-33 

requires queue element, 1-45 

summary, 1-62 
IRCVDF system subroutine, 3-33 

requires queue element, 1-45 

summary, 1-62 
IRCVD system subroutine, 3-33 

requires queue element, 1-45 

summary, 1-62 
IRCVDW system subroutine, 3-33 

requires queue element, 1-45 

summary, 1-62 
IREADC system subroutine, 3-35 

requires queue element, 1-45 

summary, 1-62 
IREADF system subroutine, 3-35 

requires queue element, 1-45 

summary, 1-62 
IREAD system subroutine, 3-35 

requires queue element, 1-45 

summary, 1-62 
IREADW system subroutine, 3-35 

requires queue element, 1-45 

summary, 1-62 
IRENAM system subroutine, 3-40 

summary, 1-61 

USR requirements, 1-42 
IREOPN system subroutine, 3-41 

summary, 1-63 
ISAVES system subroutine, 3-42 

relationship to IREOPN, 3-41 

summary, 1-63 



ISCHED system subroutine, 
3-43 

cancelled by ICMKT, 3-15 

requires queue element, 1-45 

summary, 1-64 
ISCOMP system subroutine, 3-89 

summary, 1-66 
ISDATC system subroutine, 3-44 

requires queue element, 1-45 

summary, 1-62 
ISDATF system subroutine, 3-44 

requires queue element, 1-45 

summary, 1-62 
ISDAT system subroutine, 3-44 

requires queue element, 1-45 

summary, 1-62 
ISDATW system subroutine, 3-44 

requires queue element, 1-45 

summary, 1-62 
ISDTTM system subroutine, 3-47 

summary, 1-64 
ISFDAT system subroutine, 3-47 

summary, 1-61 
ISLEEP system subroutine, 3-48 

requires queue element, 1-45 

summary, 1-64 

using, 1-56 
ISPFNC system subroutine, 3-49 

requires queue element, 1-45 

summary, 1-65 
ISPFNF system subroutine, 3-49 

requires queue element, 1-45 

summary, 1-65 
ISPFN system subroutine, 3-49 

requires queue element, 1-45 

summary, 1-65 
ISPFNW system subroutine, 
3-49 

requires queue element, 1-45 

summary, 1-65 
ISPY system subroutine, 3-55 

restrictions, 1-45 

summary, 1-67 
ISR 

See Interrupt service routines 
ITIMER system subroutine, 3-55 

cancelled by ICMKT, 3-15 

requires queue element, 1-45 

rescheduling FORTRAN subroutines, 
3-44 

summary, 1-64 
ITLOCK system subroutine, 3-57 

summary, 1-65 

using, 1-44 

USR requirements, 1-42 
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ITTINR system subroutine, 3-57 

multiterminal equivalent, 3-79 

summary, 1-62 
ITTOUR system subroutine, 3-59 

multiterminal equivalent, 3-80 

summary, 1-62 
ITWAIT system subroutine, 3-59 

relationship to SUSPND/RESUME, 
3-93 

requires queue element, 1-45 

summary, 1-64 

using, 1-56 
lUNTIL system subroutine, 3-60 

requires queue element, 1-45 

summary, 1-64 

using, 1-56 
IVERIF system subroutine 

See VERIFY system subroutine 

summary, 1-66 
IWAIT system subroutine, 3-61 

summary, 1-62 

use with ISPFN, 3-49 
IWRITC system subroutine, 3-61 

requires queue element, 1-45 

summary, 1-62 
IWRITE system subroutine, 3-61 

requires queue element, 1-45 

summary, 1-62 
IWRITF system subroutine, 3-61 

requires queue element, 1-45 

summary, 1-62 
IWRITW system subroutine, 3-61 

requires queue element, 1-45 

summary, 1-62 

JADD system subroutine, 3-64 

summary, 1-65 
JAFIX system subroutine, 3-65 

summary, 1-65 

using, 1-57 
JCMP system subroutine, 3-65 

summary, 1-65 
JDFIX system subroutine, 3-66 

summary, 1-65 

using, 1-57 
JDIV system subroutine, 3-66 

summary, 1-66 
JICVT system subroutine, 3-67 

summary, 1-66 

using, 1-57 
JJCVT system subroutine, 3-68 

summary, 1-66 
JMOV system subroutine, 3-68 

summary, 1-66 



JMUL system subroutine, 3-69 

summary, 1-66 
Job status word 

See JSW 
JSUB system subroutine, 3-69 

summary, 1-66 
JSW 
bit 11, 2-44 
bit 12, 1-23 
effect on terminal input, 2-140 
relationship to ITTINR, 3-57 
bit 14, 2-55 

effect on terminal input, 2-140 
relationship to ITTINR, 3-58 
bit 3, 2-55 
bit 4, 2-140 
bit 5, 2-44 
bit 6 
compared with M.TSTS bit 6, 2-79 
relationship to .TTINR, 2-139 
relationship to .TTOUTR, 2-141 
relationship to ITTINR, 3-57 
relationship to ITTOUR, 3-59 
bit 8, 2-5 

issue .MTRCTO or .RCTRLO after 
changing, 2-95 
JTIME system subroutine, 3-70 
summary, 1-64 
using, 1-56 

Keyword macro arguments 
description, 1-11 

LEN system subroutine, 3-70 

summary, 1-58, 1-66 
.LNKRT graphics macro, A-5 
LOAD keyboard command 

before running foreground job, 2-45 

fills in $FKPTR, 2-48 

relationship to .SRESET, 2-131 

relationship to handler termination 
table, 2-35 

relationship to IDELET, 3-19 
.LOCK programmed request, 2-62 

compared to .TLOCK, 2-136 

effect of .EXIT, 2-44 

relationship to .CSIGEN, 2-21 

summary, 1-33 

using, 1-16 
LOCK system subroutine, 3-71 

summary, 1-65 

USR requirements, 1-42 
Logical job names, 2-67 

assigning, 1-25 
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.LOOKUP programmed request, 2-65 
done by .CSIGEN, 2-16 
not done by .CSISPC, 2-21 
on a protected file, 2-49 
relationship to .CLOSE, 2-8 
relationship to .CSTAT, 2-24 
relationship to .ENTER, 2-42 
relationship to .READx, 2-100 
relationship to .REOPEN, 2-109 
relationship to .SAVESTATUS, 2-110 
relationship to .SERR, 2-59 
relationship to .WRITx, 2-149 
requires device handler, 2-45 
summary, 1-33 
system job, 2-67 
using, 1-19 
Version 4, 1-29 

LOOKUP system subroutine, 3-72 
relationship to CLOSE, 3-3 
relationship to ICSI, 3-16 
summary, 1-61 
USR requirements, 1-42 

.LPEN graphics macro, A-7 

M.FCNT 

contents, 2-77 
M.TFIL 

contents, 2-77 
M.TST2 

contents, 2-78 

in multiterminal status block, 2-77 
M.TSTS 

bit 12 
relationship to .MTIN, 2-79 

bite 
relationship to .MTIN, 2-79 
relationship to .MTOUT, 2-80 

contents, 2-77 
M.TSTW 

contents, 2—78 

in multiterminal status block, 2-77 
M.TWID 

contents, 2-77 
.MAP programmed request, 2-68 

summary, 1-37 

using, 1-26 
MAXJOB 

in timer block, 2-25 
.MCALL directive 

use, 1-6 
Memory allocation 

swapping USR, 1-15 

with .SETTOP, 1-15 
Message handler 



See MQ handler 
.MFPS programmed request, 2-69 

summary, 1-34 

using, 1-18 
MMG$T 

defined by .DRDEF, 2-33 
Monitor fixed offset area 

introduction, 1-3 
Monitor services 

introduction, 1-1 
$MPPHY pointer 

in handler termination table, 2-34 
$MPPTR 

defined by .DREND, 2-34 
MQ handler 

relationship to system job .LOOKUP, 
2-67 

using, 1-25 
.MRKT programmed request, 2-71 

relationship to .CMKT, 2-9 

requires queue element, 2-93 

summary, 1-34 

using, 1-24 
MRKT system subroutine, 3-75 

cancelled by ICMKT, 3-15 

requires queue element, 1-45 

summary, 1-64 
.MTATCH programmed request, 2-73 

relationship to .MTGET, 2-77 

summary, 1-34 

using, 1-23 
MTATCH system subroutine, 3-76 

summary, 1-63 
.MTDTCH programmed request, 2-75 

summary, 1-34 

using, 1-23 
MTDTCH system subroutine, 3-78 

summary, 1—63 
.MTGET programmed request, 2-76 

relationship to .MTATCH, 2-73 

summary, 1-34 

using, 1-18, 1-23 
MTGET system subroutine, 3-79 

summary, 1-63 
.MTIN programmed request, 2-79 

summary, 1-34 

using, 1-23 
MTIN system subroutine, 3-79 

summary, 1-63 
.MTOUT programmed request, 2-80 

summary, 1-34 

using, 1-23 
MTOUT system subroutine, 3-80 

summary, 1—63 
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.MTPRNT programmed request, 2-81 

summary, 1-34 

using, 1-23 
MTPRNT system subroutine, 3-81 

summary, 1-63 
.MTPS programmed request, 2-69 

summary, 1-34 

using, 1-18 
.MTRCTO programmed request, 2-82 

summary, 1-34 
MTRCTO system subroutine, 3-81 

summary, 1-63 
.MTSET programmed request, 2-83 

summary, 1-34 

using, 1-23 
MTSET system subroutine, 3-81 

summary, 1-63 
.MTSTAT programmed request, 2-84 

summary, 1-34 

using, 1-18, 1-23 
MTSTAT system subroutine, 3-82 

summary, 1-63 
Multiterminal feature 

introduction, 1-2 
Multiterminal requests 

introduction, 1-23 
Multiterminal status block 

contents, 2-77 

contents after .MTSET, 2-83 
.MWAIT programmed request, 2-85 

relationship to .RCVDx, 2-96 

relationship to system job .LOOKUP, 
2-67 

summary, 1-37 

using, 1-23 
MWAIT system subroutine, 3-83 

requires queue element, 1-45 

summary, 1-63 

.NAME graphics macro, A-8 
.NOSYN graphics macro, A-11 

.PEEK programmed request, 2-86 

summary, 1-34 
.POKE programmed request, 2-86 

summary, 1-34 
.PRINT programmed request, 2-87 

multiterminal equivalent, 2-81 

summary, 1-34 

using, 1-22 
PRINT system subroutine, 3-83 

summary, 1-63 
Processor status word 

See PSW 



Programmed requests 
See also EMT codes 
addressing modes, 1-10 
blank arguments, 1-9 
channel numbers, 1-11 
conversion to Version 5, 1-29 
device blocks, 1-12 
errors, 1—12 
execution, 1-4 
extended memory, 1-25 
format, 1—6 
introduction, 1-1, 1-3 
keyword macro arguments, 1-11 
registers available, 1-11 
summary, 1-32 
using, 1-15 

USR requirements, 1-13 
Version 1, 1-27 
Version 2, 1-28 
Version 3, 1-28 
Version 4, 1-29 
Version 5, 1-29 
.PROTECT programmed request, 2-88 
summary, 1-37 
using, 1-17 
PSW 

referenced by .MFPS/.MTPS, 2-69 
$PTBYT 

defined by .DREND, 2-34 
$PTWRD 

defined by .DREND, 2-34 
.PURGE programmed request, 2-90 
relationship to .CHCOPY, 2-6 
relationship to .LOOKUP, 2-65 
relationship to .SERR, 2-59 
summary, 1-34 
using, 1—19 
PURGE system subroutine, 3-84 

in place of CLOSE, 3-3 
$PUTBYT pointer 

in handler termination table, 2-34 
PUTSTR system subroutine, 3-84 
summary, 1—58, 1—66 
USR requirements, 1-42 
$PUTWRD pointer 

in handler termination table, 2-34 
.PVAL programmed request, 2-57 
compared with .POKE, 2-86 
summary, 1-34 
to change default .ENTER size, 2-41 



Q$BLKN 
defined by .QELDF, 2-92 
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Q$BUFF 

defined by .QELDF, 2-92 
Q$COMP 

defined by .QELDF, 2-92 
Q$CSW 

defined by .QELDF, 2-92 
Q$FUNC 

defined by .QELDF, 2-92 
Q$JNUM 

defined by .QELDF, 2-92 
Q$LINK 

defined by .QELDF, 2-92 
Q$PAR 

defined by .QELDF, 2-92 
Q$UNIT 

defined by .QELDF, 2-92 
Q$WCNT 

defined by .QELDF, 2-92 
Q.BLKN 

defined by .QELDF, 2-92 
Q.BUFF 

defined by .QELDF, 2-92 
Q.COMP 

defined by .QELDF, 2-92 

relationship to .SYNCH, 2-134 
Q.CSW 

defined by .QELDF, 2-92 
Q.ELGH 

defined by .QELDF, 2-92 
Q.FUNC 

defined by .QELDF, 2-92 
Q.JNUM 

defined by .QELDF, 2-92 
Q.LINK 

defined by .QELDF, 2-92 
Q.PAR 

defined by .QELDF, 2-92 
Q.UNIT 

defined by .QELDF, 2-92 
Q.WCNT 

defined by .QELDF, 2-92 
.QELDF macro, 2-92 

relationship to .DRDEF, 2-33 

relationship to .FORK, 2-48 

summary, 1-34 
.QSET programmed request, 2-92 

effect of .EXIT, 2-44 

relationship to .RCVDx, 2-96 

relationship to .READx, 2-100 

relationship to .SRESET, 2-132 

relationship to .TWAIT, 2-143 

relationship to .WRITx, 2-148 

restrictions, 1-26 

summary, 1-34 

using, 1-16 



R.GID 

defined by .RDBDF, 2-100 
R.GLGH 

defined by .RDBDF, 2-100 
R.GSIZ 

defined by .RDBDF, 2-100 
R.GSTS 

defined by .RDBDF, 2-100 
R50ASC system subroutine, 3-85 

summary, 1-67 

using, 1-57 
RAD50 system subroutine, 3-85 

summary, 1-67 

using, 1-57 
Radix-50 support 

in SYSLIB, 1-57 
RCHAIN system subroutine, 3-86 

relationship to CHAIN, 3-2 

summary, 1-65 
.RCTRLO programmed request, 2-95 

multiterminal equivalent, 2-82 

summary, 1-34 

using, 1-22 
RCTRLO system subroutine, 3-86 

multiterminal equivalent, 3-81 

summary, 1-65 
.RCVDC programmed request, 2-95 

relationship to .SDATx, 2-113 

requires queue element, 2-93 

summary, 1-37 

using, 1-23 
.RCVD programmed request, 2-95 

relationship to .SDATx, 2-113 

relationship to system job .LOOKUP, 
2-67 

requires queue element, 2-93 

summary, 1-37 

use with .MWAIT, 2-85 

using, 1-23, 1-25 
.RCVDW programmed request, 2-95 

relationship to .SDATx, 2-113 

requires queue element, 2-93 

summary, 1-37 
.RDBBK macro, 2-99 

summary, 1-37 

using, 1-26 
.RDBDF macro, 2-99 

summary, 1-37 

using, 1-26 
.READC programmed request, 2-100 

for messages between jobs, 2-67 

requires device handler, 2-45 

requires queue element, 2-93 

summary, 1-35 

using, 1-21 
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.READ programmed request, 2-100 

for messages between jobs, 2-67 

relationship to .SAVESTATUS, 2-110 

relationsip to .CHCOPY, 2-6 

requires device handler, 2-45 

requires queue element, 2-93 

summary, 1-34 

use with .WAIT, 2-145 

using, 1-20 
.READW programmed request, 2-100 

for messages between jobs, 2-67 

requires device handler, 2-45 

requires queue element, 2-93 

summary, 1-35 

using, 1-20 
REENTER keyboard command 

after .EXIT, 1-24 

relationship to .EXIT, 2-43 
.RELEASE programmed request, 2-45 

after .FETCH, 2-46 

sometimes ignored, 2-46 

summary, 1-35 
$RELOC pointer 

in handler termination table, 2-34 
.REMOV graphics macro, A-9 
.RENAME programmed request, 2-107 

on a protected file, 2-49 

requires device handler, 2-45 

summary, 1-35 

using, 1-19 
.REOPEN programmed request, 2-109 

summary, 1-35 

using, 1-19 
REPEAT system subroutine, 3-87 

summary, 1-58, 1-66 
.RESTR graphics macro, A-9 
RESUME system subroutine, 3-87 

relationship to SUSPND, 3-93 

summary, 1-65 
$RLPTR 

defined by .DREND, 2-34 
RONLY$ 

defined by .DRDEF, 2-33 
RS.CRR 

defined by .RDBDF, 2-100 
RS.NAL 

defined by .RDBDF, 2-100 
RS.UNM 

defined by .RDBDF, 2-100 
.RSUM programmed request, 2-130 

effect of .TWAIT, 2-144 

relationship to .SRESET, 2-132 

summary, 1-37 



.SAVESTATUS programmed request, 
2-110 

relationship to .ENTER, 2-42 

relationship to .LOOKUP, 2-65 

relationship to .PURGE, 2-90 

relationship to .REOPEN, 2-109 

summary, 1-35 

using, 1-19 
.SCCA programmed request, 2-112 

summary, 1-35 
SCCA system subroutine, 3-88 

summary, 1-65 
SCOMP system subroutine, 3-89 

summary, 1-58, 1-66 
SCOPY system subroutine, 3-89 

summary, 1—58, 1—66 
.SCROL graphics macro, A-9 
.SDATC programmed request, 2-113 

relationship to .RCVDx, 2-96 

requires queue element, 2—93 

summary, 1-37 

using, 1-23 
.SDAT programmed request, 2-113 

relationship to .RCVDx, 2-95 

relationship to system job .LOOKUP, 
2-67 

requires queue element, 2-93 

summary, 1-37 

use with .MWAIT, 2-85 

using, 1-23, 1-25 
.SDATW programmed request, 2-113 

relationship to .RCVDx, 2-96 

requires queue element, 2-93 

summary, 1-37 
.SDTTM programmed request, 2-117 

summary, 1-35 

using, 1-18 
SECNDS system subroutine, 3-90 

instead of .GTIM, 2-52 

summary, 1—64 
.SERR programmed request, 2-58 

relationship to .DELETE, 2-27 

relationship to .ENTER, 2-42 

summary, 1-35 

using, 1-17 
SETCMD system subroutine, 3-91 

summary, 1-65 
SET keyboard commands 

relationship to .DRSET, 2-35 

SET EXIT NOSWAP 
relationship to .EXIT, 2-43 
relationship to .SETTOP and USR, 
2-120 
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SET EXIT SWAP 
relationship to .EXIT, 2-43 

SET TT QUIET 
relationship to .GTLIN, 2-55 

SET USR NOSWAP 
relationship to .SETTOP, 2-119 
relationship to LOCK/UNLOCK, 
3-72 
SET option table 

defined by .DRSET, 2-35 
.SETTOP programmed request, 2-119 

in XM monitor, 2-121 

restrictions, 1-26 

summary, 1-35 

using, 1-15 
.SFDAT programmed request, 2-122 

relationship to .RENAME, 2-108 

requires device handler, 2-45 

summary, 1-35 

using, 1-20 
.SFPA programmed request, 2-123 

relationship to .CNTXSW, 2-10 

summary, 1-35 

using, 1-17 
Single-job monitor 

See SJ monitor 
Single-line editor 

relationship to .TTYIN, 2-140 
SJ monitor 

introduction, 1-2 
.SPCPS programmed request, 2-124 

summary, 1-37 

using, 1-22 
Special (single-character) mode for 

terminal, 1-23 
SPECL$ 

defined by .DRDEF, 2-33 
SPFUN$ 

defined by .DRDEF, 2-33 
.SPFUN programmed request, 2-126 

bit in device status word, 2-38 

function codes, 2-127 

requires device handler, 2-45 

summary, 1-35 

using, 1-17 
.SPND programmed request, 2-130 

effect of .TWAIT, 2-144 

relationship to .SRESET, 2-132 

summary, 1-37 

using, 1-24 
.SRESET programmed request, 2-131 

performed by .HRESET, 2-61 

relationship to .CDFN, 2-3 
relationship to .LOOKUP, 2-65 



relationship to .PURGE, 2-90 

relationship to .QSET, 2-93 

summary, 1-35 

using, 1-24 
Stack pointer 

caution with .CHAIN, 2-5 

during .EXIT, 2-44 
.START graphics macro, A-10 
START keyboard command 

after .EXIT, 1-24 

relationship to .EXIT, 2-43 
.STAT graphics macro, A-10 
.STOP graphics macro, A-11 
STRPAD system subroutine, 3-91 

summary, 1-58, 1-66 
SUBSTR system subroutine, 3-92 

summary, 1-58, 1-66 
Suspension of a program, 1-24 
SUSPND system subroutine, 3-93 

relationship to RESUME, 3-87 

summary, 1-65 
.SYNC graphics macro, A-11 
.SYNCH macro, 2-132 

relationship to .SPND/.RSUM, 2-130 

summary, 1-35 

using, 1-21, 1-26 
SYSCOM area 

introduction, 1-3 
SYSLIB.OBJ 

additional services, 1-56 

introduction, 1-1 
SYSLIB functions, 3-1 

channel, 1-63 

character string, 1-57, 1-66 

data transfer, 1-62 

date and time, 1-56 

device and file, 1-63 

file-oriented, 1-61 

INTEGER*4, 1-41, 1-56, 1-65 

miscellaneous, 1-67 

program suspension, 1-56 

Radix-50, 1-57, 1-67 

RT-11 services, 1-64 

summary, 1-61 

timer, 1-64 
SYSLOW, 2-121 
SYSMAC.MAC 

listing, B-1 
SYSMAC.SML 

description, 1-6 

introduction, 1-1 

macros for device handlers, 1-27 

macros for interrupt service routines, 
1-26 
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System communication area 

See SYSCOM area 
System jobs 

communicating with, 1-25 

.LOOKUP, 2-67 
System job support 

introduction, 1-2 
System macro library 

introduction, 1-1 

listing, B-1 
System status 

how to get, 1-18 
System subroutine library 

calling conventions, 1-46 

capabilities, 1-38 

channel numbers, 1-39 

completion routines, 1-39 
restrictions, 1-40 

conventions, 1-38 

device blocks, 1-41 

FORTRAN/MACRO interface, 1-47 

introduction, 1-1 

subroutine argument block, 1-47 

subroutine register usage, 1-48 

system restrictions, 1-45 

using, 1-37 



Terminal I/O 

introduction, 1-22 

special mode, 1-23 
Termination of a program, 1-24 
TIM$IT 

defined by .DRDEF, 2-33 
TIMASC system subroutine, 3-94 

instead of .GTIM, 2-52 

summary, 1—64 

using, 1-56 
Time 

internal format, 2-118 

set by .SDTTM, 2-118 
TIME keyboard command 

relationship to GTIM system 
subroutine, 3-7 
Timer block format, 2-25 
Timer support 

introduction, 1-24 
TIME system subroutine, 3-95 

instead of .GTIM, 2-52 

summary, 1-64 
.TIMIO macro, 2-135 

relationship to .CTIMIO, 2-25 

relationship to .DRDEF, 2-33 

summary, 1-35 

timer block format, 2-25 



$TIMIO pointer 

in handler termination table, 2-34 
$TIMIT 

defined by .DREND, 2-34 
.TLOCK programmed request, 2-136 

summary, 1-35 

using, 1-16 
.TRACK graphics macro, A-11 
TRANSL system subroutine, 3-95 

summary, 1-58, 1-66 
TRIM system subroutine, 3-97 

summary, 1—58, 1—66 
.TRPSET programmed request, 2-137 

summary, 1-35 

using, 1-17 
.TTINR programmed request, 2-139 

summary, 1-36 

using, 1-22 

with indirect command file, 2-56 
.TTOUTR programmed request, 2-141 

summary, 1—36 

using, 1-22 

when to use .PRINT, 2-88 
.TTYIN programmed request, 2-139 

multiterminal equivalent, 2-79 

summary, 1-36 

using, 1-22 

with indirect command file, 2-56 
.TTYOUT programmed request, 2-141 

multiterminal equivalent, 2-80 

summary, 1-36 

using, 1-22 

when to use .PRINT, 2-88 
.TWAIT programmed request, 2-143 

relationship to .CMKT, 2-10 

relationship to .SPND/.RSUM, 2-130 

requires queue element, 2-93 

summary, 1-36 

using, 1-24 

Version 5, 1-29 

.UNLNK graphics macro, A-12 
.UNLOCK programmed request, 2-62 

implicit by .CSIGEN, 2-16, 2-21 

implicit by .CSISPC, 2-22 

performed by .EXIT, 2-44 

summary, 1-36 

using, 1-16 
UNLOCK system subroutine, 3-97 

relationship to LOCK, 3-71 

summary, 1—65 
.UNMAP programmed request, 2-145 

relationship to .MAP, 2-68 

summary, 1—37 

using, 1-26 
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.UNPROTECT programmed request, 
2-88 

summary, 1-37 

using, 1-17 
User service routine 

See USR 
USR 

ownership by different jobs, 2-136 
USR locking 

effect of .LOCK, 2-62 

effect of UNLOCK system subroutine, 
3-97 

how to minimize, 1-44 

relationship to .CSIGEN, 2-16 

using LOCK system subroutine, 3-71 
USR requirements 

.CLOSE, 2-8 

FORTRAN interface, 1-42 

programmed requests, 1-13 

swapping, 1-14 
USR swapping 

controlling, 1-15, 1-43, 2-110 

effect of .LOCK, 2-62 

strategies, 1-43 



..VI.. macro 

summary, 1-36 
..V2.. macro 

summary, 1-36 
VARSZ$ 

defined by .DRDEF, 2-33 
VERIFY system subroutine, 3-98 

summary, 1-58, 1-66 
Version 1 

differences, 1-27 
Version 2 

differences, 1-28 
Version 3 

differences, 1-28 
Version 4 

differences, 1-29 
Version 5 

differences, 1-29 
VTBASE.OBJ display file handler 

module, A-2, A-15 
VTCALl.OBJ display file handler 

module, A-2, A-15 
VTCAL2.0BJ display file handler 

module, A-2, A-15 
VTCAL3.0BJ display file handler 

module, A-2, A-15 
VTCAL4.QBJ display file handler 
module, A-2, A-15 



VTHDLR.OBJ concatenated display 

modules, A-2, A-16 
VTLIB.OBJ display file handler library, 
A-2, A-15 
components, A-16 
linking, A-16 
VTMAC.MAC 
listing, A-25 
VTMAC.MAC display file handler 
macros, A-2, A-15 



W.NAPR 

defined by .WDBDF, 2-148 

modified by .GMCX, 2-51 

use with .CRAW, 2-12 
W.NBAS 

defined by .WDBDF, 2-148 

modified by .GMCX, 2-51 
W.NID 

defined by .WDBDF, 2-148 
W.NLEN 

defined by .WDBDF, 2-148 

modified by .GMCX, 2-51 
W.NLGH 

defined by .WDBDF, 2-148 
W.NOFF 

defined by .WDBDF, 2-148 

modified by .GMCX, 2-51 
W.NRID 

defined by .WDBDF, 2-148 
W.NSIZ 

defined by .WDBDF, 2-148 

modified by .GMCX, 2-51 
W.NSTS 

defined by .WDBDF, 2-148 

modified by .GMCX, 2-51 

use with .CRAW, 2-12 
W.RID 

modified by .GMCX, 2-51 
.WAIT programmed request, 2-145 

compared with .MWAIT, 2-85 

summary, 1-36 

use with .CSIGEN, 2-16 

use with .READx, 2-101 

using, 1-20 
.WDBBK macro, 2-147 

summary, 1-37 

using, 1-26 
.WDBDF macro, 2-148 

automatically called by .WDBBK, 
2-147 

summary, 1-37 

using, 1-26 
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WONLY$ 
defined by .DRDEF, 2-33 

.WRITC programmed request, 2-148 
for messages between jobs, 2-67 
relationship to .CSTAT, 2-24 
requires device handler, 2-45 
requires queue element, 2-93 
summary, 1-36 
using, 1-21 

.WRITE programmed request, 2-148 
for messages between jobs, 2-67 
relationship to .CHCOPY, 2-6 
relationship to .CSTAT, 2-24 
relationship to .SAVESTATUS, 2-110 
requires device handler, 2-45 
requires queue element, 2-93 
summary, 1-36 
to a protected file, 2-49 
use with .WAIT, 2-145 
using, 1-20 

.WRITW programmed request, 2-148 
for messages between jobs, 2-67 
relationship to .CSTAT, 2-24 



requires device handler, 2-45 

requires queue element, 2-93 

summary, 1-36 

using, 1-20 
WS.CRW 

defined by .WDBDF, 2-148 

use with .CRAW, 2-12 
WS.ELW 

defined by .WDBDF, 2-148 

use with .CRAW, 2-12 
WS.MAP 

defined by .WDBDF, 2-148 

effect on .CRAW, 2-12, 2-13 

optional argument to .WDBBK, 2-147 
WS.UNM 

defined by .WDBDF, 2-148 
WS.VNM 

use with .CRAW, 2-12 



XM monitor 
introduction, 1-2 
using, 1-25 
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